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PREFACE 


The MRX/OS Control Program and Data Management 
Services are discussed in two separate documents, each 
designed for a specific type of input/output (1/O) level 
user. This document, the Basic Reference manual, 
contains information at the. logical 1/O level of processing 
where the blocking and deblocking of data is done for the 
user. The Extended Reference manual is designed for the 
block and physical 1!/O level user. Block 1/O level 
processing recognizes no logical records; therefore, all data 
is read or written as a data block. The physical |/O level of 
processing allows the user to do his own processing of 
data. 


This document provides a detailed discussion of the basic 
MRX/OS facilities provided. Also included is a list of all 
macros and associated keyword parameters needed to 
execute Data Management, Control Program Services, and 
console communication facilities at the logical I/O level. 


Additional and more detailed information may be found 
in the following documents. 


@ MRX/OS Control Language Services, Extended 
Reference 


e MRX/OS Control Program and Data Management 
Services, Extended Reference 


e MRX/OS Assembler Reference 
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1. INTRODUCTION 


Through the use of Data Management and Control 
Program Services, the MRX/OS provides the easiest and 
most convenient coding methods for organizing and 
performing input/output (1/0) operations and for direct 
implementation by the system’s Control program. 


The system provides the basic user with the following 
facilities at the Assembler language level. 


1. 


Data Management 


At the logical I/O level of processing, the 
Data Management facility provides sequential 
and random access methods, three file 
organizations (sequential, relative, and 
indexed), device independence, and logical 


record processing with and without a record 


area. 


Control Program Services 


Basic Control Program Services available 
include time and date retrieval, and console 


communication. 


Debugging 


Debugging capabilities are provided by the 
CHECKOUT routine which allows the pro- 
grammer, through debug request cards in 
the Control Language statements, to call 
for a_ selection of register and main- 
storage dumps. 
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2. RECORDS, FILES, AND LABELS 


Before considering how processing works within the 
MRX/OS, an idea of what will be processed is necessary. 
This section describes the data in terms of records, files, 

- and labels, and Section 3 discusses the data in terms of 

processing. 


The processing of data files is partially determined by the 
type of file organization. Sequential files can only be 
processed sequentially, while relative files and indexed 
files can be processed both sequentially and randomly. 
Efficiency in processing is provided by the common data 
formats of the file records and labeling of the files. 


Throughout this section, several macros are referenced 
in the discussions of the records, files, and labels. 
Section 6 contains a detailed discussion of each macro 
and its function. 


Table 2-1 gives the legal device usage for file organization, 


record type, and access. 
Table 2-1. Legal Usage by Device 


Unit Record 


Organization 


Sequential 
Relative 
Indexed 


Record Type 


Fixed 
Variable 


Access 


Sequential 
Random 


RECORDS 


A record can be fixed or variable length and can vary in 
size up to 32K bytes of alphanumeric and/or special 
characters. 


The actual size of a file (determined by the length and 
number of records), file organization, and programming 
requirements are all important to file processing. 
Variable length records can be placed on either sequen- 
tial or relative files; however, the maximum record length 
must be determined and stated in program coding. In- 
dexed files are limited to fixed length records. 


DATA FORMAT 


All data stored by Data Management at the logica! 1/O 
level on disc or magnetic tape is in a common format, 
except for absolute program images. This format includes 
logical record headers and optional space headers (disc 
files) in each block of data. The common format provides 
the following advantages: 


e Efficiency of processing and decreased mem- 
ory requirements for the GET/PUT level 
blocking and deblocking functions 


e Increased data recoverability by making it 
possible to process logical records (at the 
physical !/O level) without reference to 
associated cataloging or indexing information 


e More complex file organizations or access 
methods for which the record headers will 
contain additional information 


The control information (record headers and space headers) 


is managed by the system for users working at the logical 
1/O level. 


2-1 


Records and Record Headers 


A logical record is a contiguous string of user-defined 
data within a block of data. A record header is a 4-byte 
field which precedes each logical record in the block. 
The first byte of the record header is a record identi- 
fier which is unique to that block. The format of a 
record header is as follows: 


RECORD HEADER 
a ee 


012 567 


Ne aan , 


Byte 0 Byte 1 Bytes 2 and 3 


CB — control byte 


Bits O and 1 specify data type. 


01 user data 


10 system data (for example, catalog 
records) 


11. user and system data (for example, . 
index records) 


Bit 2 specifies last data record for Library 
member only. 


0 data record in library member 
1 last data record in_ library 
member 


Bits 3 through 5 are reserved for future 
system use. 


Bits 6 and 7 are always 105 to specify two 
bytes as the length of the record length 
field (bytes 2 and 3 of the record header). 


1D — record identifier 


RL — logical record length (in bytes) exclusive 
of record header 


Block 


A block is the smallest unit of data which is processed at 
the block I/O level. Files are collections of blocks, all of 
equal length on disc and unit record devices and of 
variable length on magnetic tape. Blocks are made up of 
logical records with record headers and may have unused 
space which is preceded by a space header. !n a sequential 
file, records (fixed or variable length) follow in succession 
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without space between records; available space is at the 
end of the block. Since indexed files are made up of fixed 
length records only, there is no available space between 
records. In a relative file, however, records may have 
available space between variable length records (blocks are 
formated in increments of the longest variable length 


record) as shown: 
pie | tee | is\ 


b> tk 


H1 SH1 H2 SH2 


H1, H2 — record headers 
R1, R2 — logical records 
-SH1, SH2 — space headers (optional) 
SP — available space (optional) 
Space headers are 1- to 3-byte fields which describe and 


precede unused space in blocks. The format of a space 
header is as follows: 


012 567 

; | ce | NBA 

Se rr 
Byte 0 Bytes 1 and 2 


CB — control byte 


Bits 0 and 1 are OO to specify available 
space rather than data. 


Bits 2 through 5 are reserved for future 
system use. 


Bits 6 and 7 specify the byte length of 
the NBA. 


00 one byte of space available (only 
CB present) 


01 two bytes of space available (CB 
and one byte of NBA containing 
zero) 

10 three bytes or more of space 
available (CB and two bytes of 
NBA containing zero or the 
NBA) 


NBA — number of bytes of space available ex- 
clusive of the header. This field may be ab- 
sent, a single byte containing zero, or two 
bytes containing zero or the NBA. 


At the logical I/O level, record headers are generated by 
the system when data is stored on disc or tape and are 
removed from the data by the system when stored data is 
retrieved from these media. 


RECORD TYPE 


The data portion of a logical record may be fixed or 
variable length for files residing on magnetic tape or disc. 
Records must be fixed length for files processed from 
unit record devices. ; 


RECORD SIZE 


Data Management will support (except when maximum 
block length for a particular device imposes lower limits) 
block length between 18 bytes and 32K bytes and 
blocking of logical records up to 256 records per block. 


CONTROL CHARACTERS 


The control characters for the printer and punch are 
included as part of the data record itself, but they are not 
transferred to the output units. (Therefore, if the output 
is to the punch, 81 characters are specified for the record 


size.) The character code defines the operation of the — 


carriage control tape of a printer and the stacker selection 
of a card punch. The following lists the ANS control 
character codes and corresponding operations. 


Character 
Code Operation 


(blank) Space one line before printing 
0 Space two lines before printing 
Space three lines before printing 


+ Suppress space before printing 


1 Skip to channel 1 before printing 
2 Skip to channel 2 before printing 
3 Skip to channel 3 before printing 
4 Skip to channel 4 before printing 
5 Skip to channel 5 before printing 


6 Skip to channel 6 before printing 


7 Skip to channel 7 before printing 
8 Skip to channel 8 before printing 
9 Skip to channel 9 before printing 
A ~ Skip to channel 10 ite printing 
B Skip to channel 11 before printing 
C  __— Skip to channel 12 before printing 
V Select stacker 1 

Ww Select stacker 2 


The native device control characters are listed in the 
applicable peripheral device reference manual. 


The 1/O processing accepts both the ANS character codes 
and native device codes. The CONTROL parameter of the 
OPENL macro specifies which set of characters is being 
used. 


in calculating buffer, record area, and record sizes, the 
appropriate number of bytes must be added for the 
control characters. For example, if the record size is 96 
bytes, another byte is added for the control character; 
thus the record size and record area size is 97 bytes. 
However, only the 96 bytes of data will be printed or 
punched. 


FILES 


A file is a set of records containing related information. 
Such a set of records may be punched into cards (card 
file), printed on forms (printer file), or written on mag- 
netic tape (tape file) or disc (disc file). 


Files are organized in specific manners: sequential, rela- 
tive, and indexed. Files can be classified according to 
their function within the job structure: scratch, temporary, 
work, or permanent. The following paragraphs describe 
the files according to organization and type (classifica- 
tion). 
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FILE ORGANIZATION 


Files assigned to unit record and magnetic tapes are 
always organized as sequential files. 


Random access devices, such as the disc, remove the re- 
strictions of sequential organization and sequential proc- 
essing. Disc flexibility allows for all three types of 
organization and, consequently, the associated methods 
of file processing. 


Sequential Files 


Sequential files apply to all media: disc storage, magnetic 
tape, and unit record devices. Records are written in 
consecutive locations for sequential file organization. The 
order of the records when the file is created (Figure 2-1) 
determines the sequence for processing the file later. 


Sequential organization limits processing. Records can 
only be retrieved sequentially beginning with the first 
record of the file and subsequently retrieving each 
record in the file. Any changes, additions, or deletions 
to a magnetic tape or card file involves recopying the 
entire file. The additions are included in the file and the 
deletions are excluded. For a sequentially organized 
disc file, changes can be made to individual records 
without retrieving unchanged records, providing no 
additions or deletions exist. 


Relative Files 


The position of logical records in a relative file is given 
by a record number relative to the beginning of the file. 
The GET/PUT logic changes this record number into 
a block number and a relative position (record identi- 
fication) within that block. 


The records are written into preformated blocks on the 
basis of the block record number (Figure 2-2). 
Preformating is accomplished at file creation time by the 
OPENL macro. Blocks are-preformated over the entire 
allocated space in the common stored data format with 
binary zeros in the logical record area. Record deletion or 
further maintenance of blank records is a_ user 
responsibility. 
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Relative file organization provides for sequential or 
random creation. The records are placed in a predeter- 
mined order which could be sequential or relative. 
The ACCESS parameter of the DEFRF macro determines 
the processing environment of the file. 


Indexed Files 


When indexed file organization is specified, two types of 
data are generated: the data portion of the file and the 
index portion of the file. 


Allocation of space for the index portion is performed 
automatically when the data file is allocated. The user 
requests allocation through the Control Language 
DEFINE cards and may control placement of both the 
data portion and the index portion to the pack and 
cylinder level if desired (index portion may, therefore, be 
on same pack as data portion or on a separate pack). 


The number of blocks needed for the index portion is 
calculated by the allocation routine from the number of 


' data blocks estimated, the key length, and the number of 


keys per block specified. 


Appendix D gives the layout of the index portion of the 
file. 


Data Portion of Indexed File 


The data portion of an indexed file is written into blocks 
that have been preformated by the OPENL macro at disc 
file creation. As successive blocks are written, they are 
scattered around each disc track so that a fixed number of 
blocks may separate two logically consecutive blocks on a 
track. The number of blocks separating logically 
consecutive blocks can vary from 0 to 9. Scattering is 
done to increase the probability that two successive data 
block readings can be performed without losing a disc 
revolution. The number of blocks which separate logically 
consecutive blocks is determined by a spread factor 
established as a file attribute through the allocation 
process. 


CARD FILE 


RECORD 5 
RECORD 4 


RECORD 3 


— 


RECORD 2 


Riccio. ee 


| Records are placed in | 
. consecutive locations 
| on the disc, | 


aS estima 


RECORD 1 


DISC FILE 


RECORD 4 RECORD 5 z= 


RECORD 2 RECORD 3 


W RECORD 1 


Figure 2-1. Sequential File Organization 
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Figure 2-2. Relative File Organization 
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- 7 = 


r 
The directory to the directory index, 
| whichis located on disc, and maybe | 
| processed on disc or in main storage, 1 
| gives the first value in each directory =| 
| block. The directory index gives the | 
| first value in each primary index | 
| block. The primary index, in turn, | 
| | 
| | 
| 1 
| j 
| | 
L 


index block number 


gives the associated block record 
address for a key value. Entries in 
the directories are assembled in 
ascending order according to the 
keys. 


Figure 2-3. Indexed File Organization 


Index Portion of Indexed File 


The locations of logical records in data files are recorded 
in an index portion of the file by means of a three-level 
table look-up indexing scheme (Figure 2-3). Each record 
has a unique primary index key value, which is recorded 
with the block record number in the primary level index 
block at file creation time. A directory level index, which 
locates the primary index blocks for random access, is also 
generated at file creation time. Another index, a directory 
to the directory level index is also generated. This 
additional directory is read into main storage (if specified 
by the INMAIN parameter of the DEFIF macro) at the 
opening of the file, thus increasing the efficiency of 
random retrieval. 


Random access is performed by reading the directory to 
the directory index and the directory blocks, followed by 
an access to the appropriate primary index block. The 
data is then accessed by the block record number found in 
the primary index block. 


Sequential access is performed by main-storage processing 
of primary index blocks. A look-ahead process for a 
change in block number within each index block provides 
the overlap of data block transfer with logical record 
processing. A linkage chain among primary index blocks is 
used to handle overflow of the primary index blocks. 


Creation of indexed files requires that the data be 
presented in the ascending order of the collating sequence 
of the primary key values. As data blocks are created, the 
index information is generated by the GET/PUT modules 
for indexed files and written in the index blocks. A ten 
percent margin remains in each index and directory block 
to accommodate the addition of data records. 


Indexed files may be extended by addition of more data 
records, presorted in the sequence of the primary index 
key values, if the key value of the first data record of the 
extension is greater than the highest key value processed 
during creation. This extension is performed by specifying 
output usage in the OPENL macro. The positioning to the 
end of current information and initializing tables is 
performed by the OPENL macro. No previous updates are 
allowed if the file is to be extended. 


Data may be added, deleted, or updated either randomly 
or sequentially by opening for update usage. When data 
records are added they are written after the current last 
record in the data portion of the file. A record address is 
then inserted into the appropriate primary index block. If 
additions of many records in the same region of primary 
index causes the primary index block to overflow, a new 
block is linked into the first level linkage chain and some 
- of the record addresses in the block which overflowed are 


moved into this new block to minimize the chance of 
further overflow in the same area. 


When data is deleted, the index information for the 
deleted record is removed, but the data record is not 
modified. 


FILE TYPE 


Each file has a disposition type (scratch, temporary, 
work, or permanent) established when space is alloca- 
ted for the file. 


Scratch 


Scratch files are used by jobs that have several job steps. 
These files exist only for the duration of a job step and, at 
the end of the job step, are purged by system control. The 
file is positioned at the beginning of the file by the 
OPENL macro. Scratch files cannot have an indexed file 
organization. 


Temporary 


Temporary files provide a temporary storage area for job 
processing. They exist only for the duration of the job 
and, at the end of the job, are purged by system control. 
The file is positioned at the beginning of the file by the 
OPENL macro. Temporary files cannot have an indexed 
file organization. 


Work 


Work files occupy permanently allocated space; how- 


- ever, the file data exists only for the duration of a job. 


If a work file is opened for output use, the pointer for 
placement of the data is positioned to the beginning 
of the file. Work files must have sequential file organi- 
zation. 


Permanent 


Permanent files occupy permanently allocated space and 
the file data is permanent. If a permanent sequential file is 
opened for output use, the data is added to the end of the | 
file. For relatively organized files, the records are added 
wherever specified. For indexed files data is added to the 
end and must be presented in the collating sequence of 
the primary key beginning above the current high key 
value. 
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SUMMARY OF FILE TYPES BY ORGANIZATION 


Table 2-2 provides an easy reference to the file types 
allowed for each file organization. It notes how records 
are added to permanent files. 


Table 2-2. File Types By Organization 


File 
Organization 
Sequential Relative 


Permanent 
Records Records Records 
are are are added 
added to added to the end 
the end wherever of file 
of file user 
specifies 


ieee POINT 


Indexed 


LABELED 


LOAD POINT 


LABELS AND CATALOGS 


File labels ensure the opening of a correct file for a 
particular job. The OPENL macro checks the file for 
the proper name and attributes. Since Data Management 
handies labels and catalogs, the basic user need not 
be concerned with the physical aspects of label and 
catalog checking (the Control Program. and Data 
Management Services, Extended Reference manual pro- 
vides this information). 


TAPE LABELS 


Tape labels are special records at the beginning and end of 
magnetic tape files (Figure 2-4). They are used to identi- 
fy the reel of tape and the succeeding file, as well 
as certain information for file maintenance. All labels 
may not have the same format. Some tapes may be un- 


labeled and others may have user-supplied nonstandard 
label formats. 


VOLUME} HEADER | HEADER | T T TIT 
TAPES Nea LABEL 1 eae] DATA RECORDS TRAILER LABEL BB 


OPTIONAL TAPE MARK 


| 
LOAD POINT 
NONSTANDARD 


TAPE LABELS 


T T 
CEN 


Figure 2-4. Tape Organization 


Standard Tape Volume Label 


The volume label is located at the beginning of a tape reel . 


and is identified by the characters, VOL, found in the first 


three positions (Figure 2-5). The volume label number is. 


always 1 for compatibility with IBM. The volume serial 
number occupies. positions 4 through 9 and identifies the 
volume. A unique owner name and address code identifies 
the installation. 


VOL 


VOLUME LABEL NUMBER 


VOLUME SERIAL NUMBER 


OWNER NAME 
: AND 
ADDRESS CODE 


Figure 2-5. Standard Tape Volume Label 


Standard Tape File Label 


The standard tape file label provides information 
concerning the user’s file such as creation and expiration 
dates, file name, and sequence number (Figure 2-6). The 
label identification field identifies the type of standard 
label with a three letter abbreviation. Three types of labels 
supported by the system are header labels (HDR), 
end-of-file labels (EOF), and end-of-volume labels (EOV). 
The file label number found in byte 3 is 1 or 2. The file 
serial number, found in positions 21-26, is identical to the 
volume serial number in the volume label of the first 
volume. The volume sequence number identifies the order 
of the volume of data records in a multivolume logical 
file. The block count provides the number of physical 
records written in a file at creation. 


HDR 


LABEL IDENTIFICATION ~— + EOF 


FILE LABEL NUMBER 


FILE NAME 


FILE SERIAL NUMBER 


VOLUME SEQUENCE NUMBER 


CREATION DATE 


EXPIRATION DATE 


BLOCK COUNT 


Figure 2-6. Standard Tape File Label 


EQV 


2-9 


DISC LABELS 


Disc packs have a standard volume label containing 
volume identification and owner information (Figure 2-7). 
The device type, owner, and state of the volume — 
unrestricted (0), restricted (1), or locked (2) — are 
included along with the starting track address of the pack 
catalog for this volume. The actual file identification is 
found in the disc catalogs. 


VOLUME IDENTIFIER 


POINTER TO VTOC (VOLUME 
TABLE OF CONTENTS) ONLY ON 
CONVERTED IBM PACKS 

‘DEVICE TYPE 


PACK CATALOG ADDRESS 


OWNER 
(1-56 BYTES EBCDIC) 


Figure 2-7. Disc Label 


Disc files are described by file labels found in the pack 
catalogs, which are resident on each disc pack in the 
system. The file labels contain the file name, file 
attributes, and a physical description of the segments of 
disc space allocated to the file on this pack. The actual 
fields of the catalogs can be found in the Control Program 
and Data Management Services, Extended Reference 
manual. 
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DISC STORAGE CATALOGS 


The space management routines (explained in the 
Control Program and Data Management Services, Extended 
Reference manual), in performing their function, main- 
tain the central catalog and pack catalogs on disc. 
The central catalog, existing once for a system, contains 
an entry for each file cataloged in the system. The 
entry identifies the file and describes the volume(s) 
occupied by the file. 


The pack catalog, existing on each volume, contains an 
entry for each file occupying space on the volume. 
The entry identifies the file and describes the space 
occupied by the file. 


3. I/O PROCESSING 


The !/O processing capabilities of MRX/OS are divided 
into three levels: logical, block, and physical. The logical 
1/O processing level, discussed in this section, blocks and 
deblocks data for the user; block 1/O_ processing 
recognizes no jJogical records (data is read or written as a 
data block); physical !/O allows the user to do his own 
1/O processing. The block and physical 1/O processing 
levels are discussed in detail in the Control Program and 
Data Management Services, Extended Reference manual. 


The logical 1/O level Data Management functions are 
provided by relocatable subroutines which are loaded with 
and linked to the user programs which request them. They 
require MRX/OS control program, system control, loader, 
and library functions. 


ACCESS METHODS 


Two access methods are provided at the logical 1/O level, 
sequential and random. 


SEQUENTIAL ACCESS 


Sequential access is a method of retrieving records 
consecutively in the order of logical arrangement in the 
file. All file organizations are sequentially accessible. 


Sequential access is the only method that can be used for 
retrieving sequentially organized file records. Relatively 
organized file records can be processed sequentially by 
beginning at the start of the file and processing each 
successive record. Indexed file records also can be 
processed sequentially by retrieving in the sequence of the 
primary key values. By using the SETL macro, all the 
records in an indexed file may be retrieved starting at the 
beginning of file, or a portion of the file may be retrieved 
by selecting a key value for the beginning of the 
processing. The SETL macro, however, is not necessary to 
start processing at the beginning of an indexed file; Data 
Management will process from the beginning unless 
otherwise specified. 


Figure 3-1 illustrates the sequential access method. 
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Figure 3-1. Sequential Accass Method 


RANDOM ACCESS 


Random access is a method of retrieving individual 
records from a file. Only relative and indexed file 
records are randomly accessible. 


For relative files, the record number of the desired 
record is changed into a block number and a relative 
position within that block. From this computed infor- 
mation the record is directly accessible. 


For indexed files, the key values specified as the actual 
keys indicate the desired records. A search in the direc- 
tory to the directory index block, the directory index 
block, and the primary index block gives the appropriate 
block record number of the desired record. The data 
record is then retrieved by the block record number. 


Figure 3-2 illustrates the random access method. 


LOGICAL RECORD PROCESSING 


Blocking/deblocking of logical records is provided by 
GET/PUT macros, which move logical records between a 
record area and an |/O buffer or which process records 
in an I/O buffer. Processing may be either sequential 
or random with a record area and one or two I/O buffers 
defined. 


BUFFER SWITCHING 


If two buffers are specified, a buffer switching process 
is performed. For a GET request, as the records are 
transferred from the second buffer, the next data block 
is simultaneously transferred into the first buffer. 
Figure 3-3 illustrates the buffer switching involved for a 
GET request. 


Buffer switching for PUT is similar to GET but in reverse 
order. Records which have been processed in the record 
area are transferred to the appropriate !/O buffer. As soon 
as the last record” has been transferred to buffer 1, the 
next record is transferred to buffer 2, and simultaneously 
buffer 1 has its records put on the output data file in 
the appropriate block. Figure 3-4 illustrates buffer 
switching for PUT requests. 


*For variable length records, this is the last whole record the 
buffer can contain. 


Buffer switching increases efficiency of processing because 
reading and processing operations occur simultaneously 
with no waiting involved. 


FILE SHARING 


OPENL checks shared files on volumes which are 
mounted on shared resources. Output usage ensures 
exclusive use of the file. Update usage ensures that no 
other program can update the file until it is closed, but 
other programs may have access to the file. Table 3-1 
indicates the legality of usage when program 1 opened the 
file and an OPENL macro from program 2 is checking for 
usage conflicts. 


Table 3-1. Usage Conflicts 


Program 1 
Usage 
Program 2 
Usage Input Update 


Legal Input Input 
Update 
Update | Input 
Output | Update 
; | Output 


BUFFER SHARING 


When buffer sharing has been specified in the define 
macro, an additional two bytes must be added to the 
buffer size. This 2-byte field is used by OPENL and 
CLOSEL to resolve buffer usage conflicts. 


SEQUENTIAL PROCESSING WITH RECORD AREA 


The GET macro transfers a block of input data into an I/O 
buffer. From the I/O buffer, the logical record goes to a 
record area. When the last logical record in a data block 
has moved to a record area, the buffer is refilled. If a 
second 1/O buffer is specified, buffer switching is per- 
formed; contro! returns to the user when the buffer 
switching is completed. Figure 3-5 illustrates the GET re- 
quest using both a record area and a buffer. 


The PUT macro moves a logical record from a record area 


into an (/O buffer. Buffers are emptied after the last 
record has been put into the current 1/O buffer or when 
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Figure 3-2. Random Access Method 
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Figura 3-5. GET Request with Record Area 
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Figure 3-6. PUT Request with Racord Area 
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Figure 3-7. GET Request Without Record Area 


| ra 


| Input Data : : 
ee | Processing of the record occurs in the buffer. | 
ee | 1 contains the address of the area of the 
| buffer available for the next logical record. | 


BUFFER RECORD 1 RECORD 2 R1 


Address of available record area 


a net el 


| After the buffer is full, the block —| 
BLOCK 1 BLOCK 2 | uocrs | AN | of data is put on the output file, | 


Figure 3-8, PUT Request Without Record Area 
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the space left in the current 1/O buffer will not contain 
the next variable length record. If a second !/O buffer 
is specified, buffer switching is performed before re- 
turning control to the user; if a second !/O buffer is not 
specified with variable length records, the next variable 
length record is not moved into the buffer until! it has 
been emptied. Figure 3-6 illustrates the PUT request 
using both a record area and a buffer. 


SEQUENTIAL PROCESSING WITHOUT A RECORD 
AREA 


GET returns to the user, in general-purpose register 1 
(R1), the address of the first data character of a logical 
record in the buffer which is available for processing. 
Buffers are refilled after the GET request for the first 
logical record of a block is made. If a second {/O buffer is 
specified, buffer switching is performed; control returns 
to the user upon switching completion. If there is only 
one I/O buffer specified, control is retained by Data 
Management until the buffer has been filled. Figure 3-7 
illustrates the GET request using only an 1/O buffer for 
processing. 


PUT returns to the user, in R1, the first character address 
in the buffer which is available for the next logical record. 
Buffers are emptied after the PUT for the first logical 
record in the block is made. If a second I/O buffer is 
specified, buffer switching is performed; control returns 
to the user upon switching completion. If there is only 
one 1/O buffer, control is retained by Data Management 
until the buffer has been emptied. Figure 3-8 illustrates 
the PUT request using only an I/O buffer for processing. 


RANDOM PROCESSING 


While in the random mode of processing, GET retrieves 
a specified record. The buffer is filled if the specified 
record is not currently in the I/O buffer. If a second I/O 
buffer is specified, it is not used. 


When a record area is used, the GET request moves the 
requested record through the I/O buffer to the record 
area; however, if only a buffer is available, the first 
character address of the record in the 1/O buffer is 
returned to the user in R1. Figure 3-9 illustrates the 
processing of a randomly retrieved record with and with- 
out a record area. 
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When a record area has been specified, the PUT macro 
empties the buffer if it contains an updated record but 
does not contain the specified record. The buffer is then 
filled with the data block that is to contain the new 
record; the record is moved into the buffer. If this is 
an update process, the data block of this particular 
record must be in the buffer before PUT transfers the 
record. (Thus a GET request is issued first.) 


While in random mode, PUT macros are processed only 
when a record area has been specified. Figure 3-10 
illustrates the processing of the PUT macro while in 
random mode. 


MAGNETIC TAPE PROCESSING 


MR X/OS supports three types of labels: 
e Standard labeled tape 
e Nonstandard labeled tape 
@ Unlabeled tape 


The default for no LABEL specification is standard labels. 
The nonstandard option is valid only for input files. 


The label type may be selected at assembly-time through 
the optional LABTYP parameter of the DEFSF macro or 
at run-time through the LABEL parameter of the 
//DEFINE statement. However, the LABEL parameter of 
the //DEFINE statement overrides any label specification 
in the BDT which is created by the DEFSF macro. 


On the //DEFINE card, the Control Language specifies 
the type of magnetic tape labels, plus two additional 


- features - ignore and bypass label processing. The LABEL 


keyword parameter has the following format: 


LABEL= 


~WeceZzn 
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DATA BLOCK1 
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i ae 
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BUFFER 
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GET transfers the data block containing the 
specified record to the 1/0 buffer. This record | 
is then placed in the record area for processing. 


———--—------ 


GET retrieves the data block and | 
| places it in the 1/0 buffer. R1 
| gives the first character address | 
| of the specified record in the 1/0 | 
buffer. 


Figure 3-9. Random Access with GET Macro 
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Figure 3-10, Random Access with PUT Macro 
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The codes are defined as: 


Code Definition 
S | Standard tape labels 
N- ‘Nonstandard tape labels | 
U Unlabeled tapes 
B Bypass label processing 


I Ignore label processing 


Chapter 2 of this manual describes the format of standard 
labels, nonstandard labels and no labels. 


OPEN TAPE FILE 


Each OPEN(L) request for a tape unit must be supported 
by a //DEFINE Control Language statement. The SYSIN 
(system input file) is searched using the IDENT field 
supplied by the OPEN macro. !f no match is found, an 
error is returned. 


Tape units are assigned for exclusive use of a job-step by 
the Step. Initiator. OPEN(L) issues a mount reel request, if 
necessary, for each unit (1 or 2 per IDENT) assigned by 
the Step .-Initiator.* The message includes volume 
identification, reel sequence number and unit number. If 
REWIND=NO is specified in the OPEN(L) macro, no 
rewind is performed before checking labels. . 


After label checking, an FDT (File Description Table) is 
built and linked into the FDT string. If the file is open for 
logical 1/O processing, buffers are prefilled, and control 
returns to the caller. 


Bypass and Ignore Tape Labels 


The bypass and ignore options of the LABEL parameter 
are valid for input files only. If ignore (I) is selected, no 
tape positioning or label checking occurs. If bypass (B) is 
selected, no label checking between existing label and the 
Control Language options occurs. 


When the bypass option is used, the first tape record is 
read. If it is a tape mark, the tape is an unlabeled one and 
is positioned at the first data record and no further 
positioning occurs. If the first record is a standard tape 
volume label, it is a standard labeled tape and a forward 
space file routine positions the tape to the first record 
beyond the label set. If the first record was neither a tape 
mark nor a standard tape volume label, an unlabeled tape 


*Step Initiator is a module of Control Language Services. 


is assumed and a backspace record routine positions the 
tape to the beginning. The user is then responsible for 
correct positioning of the tape with nonstandard labels. 


Input files must conform to the label requirements; this 
allows no operator override. If a conflict exists, a rewind 
request is issued and the operator must mount the correct 
tape reel. 


Standard Tape Labels 


When the input file has standard labels, the volume serial 
number of the tape volume label must match the 
VOLUME parameter of the //DEFINE statement; and the 
filename of the first header label (standard tape file label) 
must match the FILENAME parameter of the //DEFINE 
statement. A forward space file routine then positions the 
first data record. If the filename in the header does not 
match the FILENAME parameter, the operator receives a 
message to retry or abort. 


When the standard labels option is selected for an output 
file, standard labels both volume and header labels must 
be written on the tape. If the volume label does not exist 
on the tape, a message is issued to the operator who must 
respond with RETRY or the information necessary to 
create a standard volume label. A standard tape file label 
(HDR1) is created from the Control Language 
information. A second header label (HDR2) is written. 
with all fields of zero and followed by a tape mark. If the 
standard volume label does exist, the first header label is 
read. If HDR1 is valid, the expiration date is checked. For 
unexpired files, a message is issued; and the operator 
responds with RETRY or ACCEPT. RETRY starts the 
sequence again and ACCEPT allows the volume to be used 
as if expired. 


Nonstandard Tape Labels 


The nonstandard label option is only valid for input files. — 
A read of the first record on the tape.is issued. If the 
record is not a standard volume label, a forward space file 
positions the type beyond the header label set. 


Unlabeled Tapes 


The first record of an unlabeled input file is read. If it is a 
tape mark, the first data record is in position. If it is nota 
tape mark, a backspace record routine positions the first 
data record. 


For output files, the first record is read. If the record is a 
standard volume label, the next record is read. If the next 
record is not a HDR1 label, the file is backspaced and a 
tape mark is written. If the second record is a HDR11 label, 
the expiration date is checked. If the file is expired, the 
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file is backspaced and a tape mark written; a message 
informs the operator that a standard volume label is being 
overwritten. If HDR1 is not expired, a message is issued, 
and the operator may ACCEPT or RETRY. If the record 
is a tape mark, the correct record is in position. If the first 
record is not a tape mark nor a volume label, the tape is 
backspaced and a tape mark written. 


CLOSE TAPE FILE 


At the end of processing a tape file certain steps are taken 
according to the option selected. 


After any label processing is done, a rewind/unload is 
issued unless a CLOSE(L) with REWIND=NO_ was 
specified. The FDT is taken out of the FDT string unless 
CLOSE(L) with LOCK=YES was specified. Control is 
then returned to the caller. 


Ignore and Bypass Tape Labels 


When the ignore or bypass option is selected, no trailer 
label checking is performed. 


Standard Labels 


When processing an input file with standard labels, the last 
record (which should be an EOF record) is read. If it is 
not an EOF and the FDT indicates the end of file, a 
message is issued to the operator, and no comparison of 
block count (FDT vs. trailer label) is made. If the record is 
an EOF, the trailer label block count is compared with the 
block count for the volume; a console message indicates 
an error when the two block counts are unequal. 


After writing the last data record in an output file, a tape 
mark, an EOF trailer label with block count, and two tape 
marks are written. 


Nonstandard Labels and Unlabeled Tapes 


When processing input file with either nonstandard tape 
labels or no tape labels, no label checking occurs. After 
completion of writing an unlabeled output file, two tape 
marks are written. 


VOLUME SWITCHING 
The CLOVE(L) macro performs volume switching for 
multivolume tape files. CLOVE(L) performs header and 


trailer label processing on tapes and alternate unit 
processing on tapes. 
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Input Files Without Standard Labels 


While processing input files with the ignore, bypass, 
nonstandard, or unlabeled option, the operator must 
indicate if there are more volumes to the tape file. If this 
is the last input volume, EOF is set in the CLOVE packet, 
and control returns to the caller. If it is not the last 
volume, label processing for this volume is the same as in 
CLOSE. A REWIND=UNLOAD and a request to mount 
the next volume are issued. Label checking for the next 
volume follows the OPEN procedure. 


Output Files With No Labels 


After processing an unlabeled output tape, two tape 
marks are written and a mount the next volume is 
requested. Label processing occurs for the next volume as 
in the open routine. . 


Files with Standard Labels 


When the files have standard labels, the current volume 
processing is the same as CLOSE except the last record is 
an EOV instead of EOF. A mount message is issued for 
the next volume, and the processing continues as in 
OPEN. 


After label checking is complete, the FDT is updated if 
necessary and control returns to the caller. 


IBM TAPE PROCESSING 


A mode of processing which does not use the common 
stored data format (described in Chapter 2) will be 
available for processing of IBM format F and U magnetic 
tapes. This mode is selected on tape by specifying 
CSD=NO in the //DEFINE statement and by specifying 
BLKFAC#=n for format F and BLKFAC=1 for format U in 
the DEFSF macro. 


INTERACTION OF DATA MANAGEMENT AND 
MRX/OS CONTROL LANGUAGE 


The Control Language Services, through the //DEFINE 
statement of the Control Language, provides a run-time 
interface with some of the Data Management services. 
Rather than coding into the program all the attributes 
of each file to be processed, the user supplies certain 
information about the files in the //DEFINE statement. 
In this way changes, which might otherwise require re- 
assembly of the program, only require modification of 
the Control Language statement. Thus, the program tends 
to remain independent of such things as the name of the 
file being processed, what device or volume the file re- 
sides on, and for sequential files the type of media 
used for processing. The Control Language Services 
provides the additional service of requesting allocation 
of space for new disc files from the user supplied param- 
eters, 


For sequential files, the Control Language can change the 
file to any device. If files have the same characteristics, 
the file name specified in DEFLB and referenced by the 
OPENL macro can be overridden by the Control Language 
with different file names; that is, files other than the one 
specified by OPENL can be processed. 


At the logical !/O level, the Control Language can handle 
all the space management (allocation, expansion, and 
purging). After a control table has been set up by the 
Control Language, Data Management can use these 
parameters for OPENL/CLOVEL routines. 


When a file is opened (OPENL macro), a File Description 
Table (FDT) is established. The file attributes described 
in the table are taken from the System Control Table 
(SCT) established by the //DEFINE statement and the 
Buffer Description Table (BDT) established by the define 
macros, (The Control Language Services, Extended Refer- 
ence manual provides a detailed discussion of the at- 
tributes specified by the //DEFINE statement.) 


The CLOVEL macro uses the volume information to switch 
volumes. The file name of this macro overrides DEFLB 
macro information. 


Example 


AD eFILE4 PibetiLGeray, STAs. Sige sli 
1 1V.0.2.22.0.401010.,NUM*2.0.0.0., $2.29100. . A eee 


| I@cKST2=104, DATQUFLe. aur. be 
jekets DATAUFZ RAUF FeQ.sg. os ing 
~— RECADAr menu bg ites FJ 
: mines HARTA E Grete, ere 


The file attributes for FILE4 (cataloged as FILE4PAY) 
are as follows: 


Record size of 100 
Block size of 104 

Two buffers 

Estimated 1000 records 
Permanent disc file 

Input file 

Volume-id 104000 
Common stored data format 
Sequential organization 
Cataloged file 

Error routine 

Record area 


The OPENL macro places the file attributes in the FDT. 


The Control Program and Data Management, Extended 
Reference manual contains an exact layout of the FDT, 
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4. CONTROL PROGRAM SERVICES 


All service requests are initially interpreted by the Control 
Program, but most of them are then transferred to 
separate routines for processing. There are, however, 
certain service requests which are processed directly by 
the Control Program. The two services that fall into this 
category are program termination and time and date 
retrieval. . 


PROGRAM TERMINATION 


The program termination macro is necessary for returning 
control to the system in an orderly fashion on completion 
of a program. Three Control Program Service macros, 
HALT, EHALT, and ABEND are provided for this 
purpose. 


These macros differ primarily in their effect upon 
subsequent steps of the job. HALT (required in all 
programs) will not affect subsequent steps in any way. 
EHALT (error halt) and ABEND (abnormal end) will 
cause any subsequent job steps to be bypassed, going 
directly to the end of job. 


In addition, ABEND provides the ability to log a discrete 
binary completion code in the Job Control Table which is 
displayed on SYSOUT. ABEND also forces a dump of the 
partition, unless a DUMP=NO was coded on the 
//EXECUTE statement. 


The DUMP= keyword operand, when coded explicitly in 
the //EXECUTE statement, will cause the partition to be 
dumped or not dumped as specified, without regard to 
whether termination was via HALT or EHALT. If the 
DUMP option was not coded on the //EXECUTE 
statement, termination via HALT or EHALT will not 
cause a dump; but termination via ABEND will cause the 
partition to be dumped. 


Neither the HALT macro nor the EHALT macro requires 
any operands. ABEND requires a specification of 
completion code desired to be logged. 


Programs may also be terminated by giving control to an 
exit routine located in the system linkage area. For this 
method to work properly, the user program must not 
disturb (or must save and reload) the contents of general 
register 7 since this will be loaded by the system with the 


exit linkage address. To terminate the program a BR @7 
should be coded in place of the HALT. This method of 
termination allows the program to serve as a subroutine 
which either links back to the caller or terminates 
depending on the contents of register 7. (Appendix B 
describes the linkage conventions.) 


TIME AND DATE RETRIEVAL 


The operating system maintains the current time and date 
for access by user programs. A user program may read 
the current time and date by means of the TIME and 
SDATE macros which will return the time or date to 
a user specified storage location. Neither the time nor the 
system date may be altered by a user program (only by 
operator command), but there is a second date area 
in the system which is available for storing a date asso- 
ciated with a particular job. The user may set this job 
date to any date he wishes by means of a //SET state- 
ment in the Control Language for his job. To read the 
job date within the program the JODATE macro must be 
used. If the job date is not set in the Control Language 
statements, the system date will be used, and any JDATE 
macros in the program will then receive the system date. 


The use of TIME, SDATE, and JDATE involves specifying 
a location where the time or date is to be received. TIME 
gives the time of day in hours, minutes, and seconds while 
SDATE and JDATE have the option of calendar or Julian 


formats. 


CONSOLE COMMUNICATION 


A single macro, CONSOLE, is provided for communication - 
with the operator's console. This macro may be used both 
for sending messages to be typed on the console and for 
receiving replies from the console, 


A second macro, MESSAGE, is available to generate the 
actual message format, though this is not essential since 
the message could also be coded directly if desired (using 
Assembler data definition statements). 
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MESSAGES TO CONSOLE 


All messages to be sent to the console must conform to a 
standard format in mernory. However, if the MESSAGE 
macro is used to create the message, the programmer need 
not be concerned with this format since it wil! be 
produced correctly by the macro. 


The MESSAGE macro should be coded in a data area of 
the user program using the parameters specified under the 
MESSAGE macro description in Section 6: it must be 
given a label so that it may be referenced by the 
corresponding CONSOLE macro. 


To transmit a message to the console, a CONSOLE macro 
must be coded using a DATBUF1=symbolic address 
parameter where the symbolic address is the tag on the 
MESSAGE macro used to generate the actual message. 


The format of the message as it will be typed on the con- 
sole is as follows: 

n ii t  messagetext 
n — the message number assigned by the system. 
This will be blank unless a reply is required. 
If a reply is required, this message number must 


be included by the operator in the reply state- 
ment. 


ii — a two-character operating system source 
indicator: P1 means partition 1, P2 means parti- 
tion 2,# # means operating system. 


t — a one-character message type indicator: 
1 means informative, D means directive (re- 
quiring operator action). This is obtained from 
the type specified in the MESSAGE macro. 


messagetext -- the actual message, up to 100 
EBCDIC characters (bytes) long. 


Example 


OPERATION OPERAND 


1234 5 67 8fa[ion yas 415 16, 18] 19 20 21 22 23 24 75 26 2: 228 29:30 31 32.33 34 35 16 37 38 39 “4,41 42 43,44 43,48, 46 


ama nanan nc Ae ted A anne bat nnn 


MSG1, MSG+P | 
DATBUFI=LAGELA 


MS.62, MS.G+28. . 
ATAUFLALASELA 


Oty Fates jas eae eee eres 


DA.TSU.EL=NSG , DATSIZ101 7.5. eae 

DATATXT. 26.’ PHASE 1... ed 

e RR AGER TEP, - sis 
EMOaT ee 
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- At assembly time the MESSAGE macro at LABELA will 


create a message format with a message text area 17 bytes 
long, the first byte of which will be labeled MSG. The 
first seven bytes contained in the message text area will 
be PHASE 1 and the remaining 10 bytes wil! be filled 
with blanks. 


During execution of the program, the first MOVX instruc- 
tion will move the characters COMPLETED into LABEL A’s 
message text area displaced eight bytes to the right of 
the label MSG, thus forming the message PHASE 1 
COMPLETED. The CONSOLE macro following this 
MOVX instruction will then cause the message to be 
typed out on the console. Similarly, the second MOVX 
instruction will result in the message PHASE 1 ABORTED, 
and the CONSOLE macro following the MOV instruc- 
tion will send this message to the console. 


REPLIES FROM CONSOLE 


The link between a given output message and _ its 
cerresponding reply message is established by a message 
number which is the first character in both the message 
and its reply. This number is assigned by the system and 
typed with the output message if the message requires a 
reply (otherwise the first character position will be left 
blank). 


When the operator types the reply, the following format 
is used: 


n replytext 


n — the number of the output message to which 
the operator is replying. 


replytext — the actual reply, up to 100 
EBCDIC characters (bytes) long. 


The reply will be received by the same CONSOLE macro 
that issued the output message. (In addition to the 
DATBUF1=symbolic address parameter, a CONSOLE 
macro that is intended to receive a reply must also include 
a DATBUF2=symbolic address parameter to signal the 


system that a reply is required and to direct it to the reply 
buffer area.) 


Note that when a CONSOLE macro requires a reply, 
control will not be returned to the user program until a 
reply has been received unless RETURN=YES is coded to 
specify immediate return. 


¥ 


Example 


£1 bareuractageia’ > 5p ' - Servis 


ema Saat hig 


anne Ea tere [ae nen ae 


DAT.BUF2Z+; 


on | 


At assembly time the MESSAGE macro at LABELA will 
create an output message format containing the message 
text ENTER PASSWORD, and the MESSAGE macro 
at LABELB will create a reply message format contain- 
ing a 10-byte field reserved for the reply message text. 


During the execution of the program, the CONSOLE macro 
will cause the message 5 P1 D ENTER PASSWORD to 
be typed out on the console. The system has included 
the message number (5 for this example) so that the 
operator’s reply (which will use the same prefix) 
may be linked to the correct output message. When 
the operator enters his reply (for example, 5 molybdenum), 
the reply will be transferred to the 10-byte field re- 
served for it by LABELB. 


DATATATFC ENTER. Ansa 
Mode D .. eee ae raven anirin 
DATSI. Rieke. re er eee 
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5. PROGRAM DEBUGGING 


Included in the operating system is a debug package, 
known as CHECKOUT, for assistance in debugging 
Assembler language” programs. CHECKOUT enables the 
programmer, through debug request cards placed in his 
Control Language deck (as a data file), to call for a 
selection of register and main-storage dumps to be 
performed at specified points during the execution of his 
program. The following dynamic snapshots in 
hexadecimal format may be obtained. 


1.- General registers 
2. Any specified area of the user program 
3. The entire user and system areas 


4. : Formated system control information 


Before debugging requests may be applied to a program, 
the program must be assembled and linkage edited. 


* CHECKOUT may also be used with RPG, COBOL, and FORTRAN 
programs if an Assembler language listing of the compiler out- 
put is available, 


CHECKOUT OPERATION 


CHECKOUT operates in two phases, The first phase, 
performed immediately after the program segment to be 
debugged has been loaded, involves initializing the pro- 
gram by planting special debug service requests at 
appropriate points within it and building (within the 
system) the control information necessary for executing 
the debug request. (The nature and location of the 
planted service requests is determined by the debugging 
requirements supplied by the user with the Control Langu- . 
age statements.) 


At this point, the directives are written on the job’s 
SYSOUT file, accompanied by directive diagnostic 
messages, if any. 


The second phase, performed after the initialized pro- 
gram has been loaded and goes into execution, involves 
the processing of the previously planted service requests. 


Each debug service request overlays a user program 
instruction. This instruction is saved by CHECKOUT so 
that it may be replaced and executed on completion of 
the service request (to maintain the integrity of the user 
program). After the replaced instruction has been 
executed, the Control Program reestablishes the debug 
service request in preparation for the next time through 
the program (if any). 
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REQUESTING DEBUGGING SERVICES 


Program debugging services are requested entirely through 
the use of request cards which are placed in the job 
deck with the Control Language cards (Figure 5-1). 
This arrangement enables specific requests to be altered 
from run to run without requiring repeated reassembly 
of the program being debugged. 


When debugging services are required, the //EXECUTE 
statement associated with the program to be debugged 
must always include the parameter DEBUG=YES. This 
instructs the system to load the CHECKOUT routines 
immediately after the program itself has been foaded 
and then to transfer control to CHECKOUT. 


The types of dumps required and the circumstances in 
which they are to be performed are specified in the set 
of debugging directives coded on the request cards. 


DEBUG REQUEST CARDS 


//DATA 


//30B NAME=MYJOB 


SYSTEM 
CONTROL CARDS 


BREAK DIRECTIVE 


The BREAK directive specifies the type, location, and 
circumstances of a particular action in a debugging re- 
quest. There are three types of action that may be re- 
quested. 


1. Dump 

2. Program termination 

3. Setting or resetting of the condition flag 
(an indicator, maintained by CHECKOUT, 
used to govern the execution of condition- 
al requests”) 


The format of the BREAK directive is: 


BREAK= (breakpoint address,action 
[,type] [,interval] 
[,starting address,ending address] ) 


*For a more detailed discussion, refer to Conditional Request 
paragraph. 


Figure 5-1. Job Deck with Debug Requests 
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breakpoint address 


A 1- to 4-digit hexadecimal code specifying the address 
within the program at which this particular BREAK 
directive is to come into operation. The breakpoint 
address must be an even number (on a word boundary) 
and must point to the first word of any valid instruction 
except an SR or a service request macro (for example, 
READ or WRITE). The breakpoint address must be 
specified as a displacement within the relevant load 
module. When a program consists of a single load module 
which was produced from a single control section (the 
normal case), this displacement may be obtained directly 
from the program’s assembly listing, but when the 
program consists of multiple contro! sections/modules, 
the Linkage Editor map will also be required to calculate 
the additional control section displacements. 


action 


A 1- or 2-character code specifying the action to be per- 
formed at the breakpoint address. The following action 
codes are available. 


Code Action 


T Terminates program and dumps if type 
parameter is present 


TC Terminates if condition flag is on and 
dumps if type parameter is present 


D Dumps unconditionally 
DC Dumps if condition flag is on 
CS Turns condition flag on and dumps if 


type parameter is present 


CR Turns condition flag off and dumps if 
type parameter is present 


type (Optional) 


A 1-character code specifying the type of dump to be 
performed. The following type codes are available. 


Code Type 


R General registers only 
S General registers plus main-storage im- 


ages (in hexadecimal with EBCDIC trans- 
lations) of that section of the user 
partition defined by starting address 
and ending address 


P General registers, formated !system con- 
trol information, and main-storage im- 
ages of the entire user partition 


A General registers, formated system 
control information, and main-storage 
images of the entire user and system 
areas 


interval (Optional) 
A 1- to 3-digit decimal number (0-255) specifying the 
number of times the breakpoint address must be passed 
before the selected action is performed. No action will be 
taken on the first n-1 executions of the instruction at the 
breakpoint address; action will be taken on execution n, 
2n, 3n, etc. 


starting address,ending address (Optional) 


A pair of 1- to 4-digit hexadecimal codes specifying the 
starting and ending words of the main-storage dump. Both 
should be word addresses; if not, starting address and 
ending address will be rounded down one byte. Starting 
address and ending address must be specified as 
displacements within the partition. Starting and ending 
displacements are relative to the beginning of the user 
portion of the partition. The linkage editor map will be 
required to compute the actual offset. 
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Examples 
1. BREAK=(1064,D,R) 


When program execution reaches displace- 
ment 1064 (before executing the instruction 
at 1064), general registers are dumped. 


2. BREAK=(1098,CS) 


The condition flag is turned on when program 
execution reaches displacement 1098. 


3. BREAK=(1120,TC,S,,2000,2G80)* 


if the condition flag is on when displacement 
1120 is reached, the program terminates and 
the memory from partition displacements 
2000 to 2080 is dumped. If the condition flag 
is off at this time, no action is taken. 


4. BREAK=(1250,D,R,40) 


For the first 39 executions of program 
displacement 1250, no action is taken. At the 
40th, 80th, 120th, etc., executions, the 
general registers are dumped. 


PROG DIRECTIVE 


The PROG directive establishes the name of the load 

‘ module to which all succeeding directives apply, up to the 
point that a new PROG directive is encountered. Until the 
first PROG directive is reached, all BREAK directives 
automatically relate to the main module as specified in 
the //EXECUTE statement. Thus, the PROG directive is 
only necessary when debugging programs containing more 
than one load module. 


The format of the PROG directive is: 


PROG=program name 


program name 


The name of the load module to which all succeeding 
directives apply. 


*The extra comma indicates that the interval parameter has 
been omitted. 
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CONDITIONAL REQUESTS 


A conditional request (BREAK directive) is a request 
which is only performed in the event that the condition 
flag, maintained by CHECKOUT, is in the on condi- 
tion at the time that the request is to be implemen- 
tec. This flag may be dynamically altered during program 
execution and may thus be used to govern the execution 
of conditional requests. 


The condition flag is always in the off state at the start 
of a program. If a BREAK directive is coded to set the 
condition flag to on at a breakpoint address within a 
given program path, a conditional dump will not be 
recognized unless the program has followed the given 
program path. As a result of the condition flag stili 
being off, no conditional requests of the given program 
path will be honored (Figure 5-2). 


EXAMPLE OF JOB CONTROL DECK WITH 
CHECKOUT DIRECTIVES 


Figure 5-3 shows a typical job deck including a CHECK- 
OUT directive set calling for a variety of different 
dumps. An explanation of each card follows: 


Card 1: The //JOB card. 


Card 2: The //EXECUTE card includes the 
parameter DEBUG=YES so that the system will 
open the CHECKOUT data file and _ initialize 
CHECKOUT for each loaded module. 


Cards 3, 4, and 5: The //DEFINE cards identify 
the input file, output file, and CHECKOUT 
directive file, respectively. (Cards 3 and 4 are not 
required by CHECKOUT.) 


Card 6: The //DATA card informs the system 
that data destined for the CHECKOUT data 
file follows immediately. 


Card 7: The first of the CHECKOUT directive 
cards. The BREAK directive on this card di- 
rects CHECKOUT to turn the condition flag 
on when displacement 102A is reached within 
program COPY. (Since a PROG directive has 
not yet been issued, the program name given 
on the //EXECUTE card is assumed.) 


Sa ee cane eee al 


G5 


ss carr ee A Cy LLY Sr 


SYSTEM ACTION 
1 


| Condition flag initialized to off when 
new program ts loaded by Control 
Language Services (at start of step 


=e 


[" pewwoneauesr | 


| Turn condition flag on at this | 


address, _| 


L DEBUG REQUEST | 


Conditional dump at this address 
(will be performed only if Path B 
| was taken). 


| 
| 
Bee Wen Mercier eee eee 


Figure 5-2. Example of Use of Conditional Request 


*Note that multiple debugging directives may appear on one card, | 
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BREAK=(102A,CS) 


//JOB NAME=FIL2FIL 


13/ BREAK=(488,DC,A,150), BREAK=(488,T,,200) 
12/ BREAK=(488,0C,S,50,1000,2000),BREAK=(488,D,R) 
PROG=SEGMENT2,8REAK=(1000,CS) 

10/ BREAK=(12,0,R,10),BREAK=(888,T) 

9/ BREAK=(17FE,T,A,15),PROG=SEGMENT1 

8/ BREAK=(102E,D,R,),BREAK=(104B,0C,S,,1000,1800) 


Figure 5-3. Typical Job Deck with Debugging Directives 


Card 8: This card contains two BREAK 
directives.” The first calis for a register file dump 
at displacement 102E within COPY. The second 
BREAK directive specifies a conditional dump of 
memory between partition displacements 1000 
and 1800, to be performed at displacement 104B 
within COPY only if the condition flag is on at 
this time. 


Card 9: The BREAK directive on this card 
requests program termination and a type A dump 
to be performed on every 15th execution of the 
instruction at program displacement 17FE. The 
PROG directive indicates that from here on (until 
another PROG is encountered) all BREAK 
directives are to apply to SEGMENT1. 


Card 10: The first BREAK directive calls for a 
register dump on every 10th execution of the 
instruction at displacement 12 within 
SEGMENT1. The second BREAK directive 
specifies termination of program at displacement 
888 within SEGMENT 1. 


Card 11: From this point until another PROG 
directive is issued, all directives apply to SEG- 
MENT2. The BREAK directive calls for the 
condition flag to be turned on at displacement 
1000 within SEGMENT2. 


Cards 12 and 13: The four BREAK directives on 
these cards all apply to displacement 488 within 
SEGMENT2. The first specifies a conditional 
dump of memory locations between partition 
displacement 1000 and 2000, to be performed on 
every 50th execution of the instruction at the 
breakpoint address if the condition flag is on. The 
second calls for a register file dump on each 
execution. The third is a conditional dump of type 
A to be performed on the 150th execution. The 
fourth is an. unconditional termination of the 
whole program on the 200th execution. 


Card 14: This is the data delimiter card for 
the CHECKOUT directive data file. 


Card 15: The //EOJ card. 


but no continuation is allowed. 


This section gives the specifications for the logical 1/O 
level functions of Data Management, console communica- 
tions, and Control Program Services. In general, all the 
macros have the following format. 


Name Operation Operand 


The name field is an optional field which contains a 1- to 
8-character alphanumeric file identifier. The first six 
characters must be unique to accommodate the standard 
suffixes used by the system. These are discussed in the 
Control Program and Data Management Services, 
Extended Reference manual. 


The names ident, labadr, and tag are used as identifiers for 
the software function specified in the operation field. 


The operand field contains keyword parameters which 
may be in any order separated by commas. Optional 
parameters are denoted by brackets,[ ]. Parameters with 
a choice of specifications are denoted by braces, { , with 
the default case being underlined. 


Fields are free-form and are separated by blanks; thus, 
no imbedded blanks are allowed within the parameter 
string. If more than one card is necessary, a semicolon 
must appear after the last parameter on each card ex- 
cept the last. 


Symbolic address is the 1- to 8-character symbol used to 
identify a coding statement. Unless otherwise stated all 
numbers are assumed to be in decimal with no leading 
zeros. 


The linkage conventions for MRX/OS are found in 
Appendix B. . 


6. MACROS 


DATA MANAGEMENT MACROS 


In this section only the logical 1/O level of Data Manage- 
ment macros are given. This level of macros includes: 


e File and Label Definition Macros 


DEFSF 
DEFRF 
DEFIF 

DEFLB 


@ File Control Macros 


OPENL 
CLOSEL 
CLOVEL 


@e Data Transmission Macros 


GET 
PUT 
SETL 
LOCRC 
PUTU 
DELR 


FILE AND LABEL DEFINITION MACROS 


The declarative macros for the logical !/O fevel define 
the blocking/deblocking and label information for the 
three logical 1/O level organizations. There must be 
a file definition macro (DEFSF, DEFRF, or DEFIF) 
for each file to be opened and processed. The macros 
generate a main-storage table, the Buffer Description 
Table (BDT), which is used by the GET/PUT logic. 


The name field (ident) of the define macros is a required 
entry. This 8-character file identifier is the symbolic 
address of the BDT generated by a macro instruction. 
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DEFSF — Define Sequential File 


The DEFSF macro defines sequential files. The format for 
DEFSF is as follows: : 


Name Operation Operand 
YES 
ident DEFSF BINARY= {No | 
BLKFAC=n 
BLKSIZ=n 
SYES 
[pursue- 1NO | 


[DATBUF1=symbolic address] 


_SYES 
[pareur2-| symbolic oe 


rsymbolic address 
ER ROPT=5 \ 
1 


er 
LABTYP=< NONE 
instnol 
[RECADR=symbolic address] 


[RecRes=}\0 { 


No 
RECSIZ=n 

r 
RECTYP Ft 


[veriev={¥Est| 


BINARY=\\5 f 


NO (Optional) 


BINARY=YES indicates that files assigned to card readers 
will process binary cards; therefore, the buffer size must 
be 160 bytes rather than 80 (or in the case of punch, 161 
bytes rather than 81). If BINARY=NO or if omitted, the 
data is in EBCDIC. 


BLKFAC=n 


Designates the number of records per block (blocking 
factor). The keyword value gives an integer value of 1 
through 255. BLKFAC is required for fixed length 
records. This parameter should be used for variable length 
records only when packing is not desired; without it, 
packing will occur. 


BLKSIZ=n 


Specifies the block size of the file. The keyword value 
gives an integer value of 18 bytes through 32K bytes for 
magnetic tape and 7294 bytes for disc. The four bytes per 
record for record headers must be included when 
specifying block size for files which may be assigned to 
disc or magnetic tape. Buffer size must be greater than or 
equal to the block size of any file which uses the buffer. 


BUFSH nine (Optional) 


NO 


BUFSHR=YES indicates the I/O buffer(s) is(are) shared 
with another file. If sharing is specified, the buffer 
address(es) must be explicitly specified and the user must 
reserve two bytes (one machine word) immediately before 
DATBUF1. This word, containing zero, is used by OPENL 
and CLOSEL to resolve buffer usage conflicts. If 
BUFSHR=NO or is omitted, I/O buffers are not shared. 
OPENL and CLOSEL do not check for buffer usage 
conflicts. 


DATBUF 1=symbolic address ~ (Optional) 
Specifies the address of the first 1/O buffer, which must 
begin on an even byte boundary. When generating 
buffers, the buffer size must be greater than or equal 
to the block size of any file which uses the buffer. 
If the parameter is not specified, DEFSF generates 
a buffer equal to block size immediately following the 
BDT. 


DATBUF2= Ee : (Optional) 
symbolic address 


Specifies a second I/O buffer, which permits overlapping 
of data transfer and information processing. The buffer 
must begin on an even byte boundary. DATBUF2=YES 
results in generation of a second buffer following 
DATBUF1. If omitted, processing is from one buffer. 


symbolic address 
ERROPT=<S 
\ 


(Optional) 


Specifies one of three conditions for processing errors. 
The symbolic address gives the user control when errors 
occur. The S (skip) option and | (ignore) option (only for 
input files) skips to the next block or ignores errors, 
respectively, and processing continues. If the parameter is 
omitted, error conditions abort the job. 


STND ) 
LABTYP=< NONE 
NSTND 


(Optional) 


Determines the type of tape label processing to be per- 
formed for tape files. The parameter is ignored for non- 
tape files. The default value for files assigned to tape is 
standard label processing. The code definitions are: 


Code Definition 
STND Check labels for input files. Write stan- 
dard labels for output files. 


NONE No labels exist and no label checking is 
done. 


NSTND Nonstandard iabels exist and label check- 
ing is bypassed. The nonstandard label 
set must be terminated by a tape mark. 
The tape is positioned to the record 
following the tape mark by the OPENL 
macro. 


RECADR=symbolic address (Optional) 


' Specifies the address of a record area. The size of the 
record area must be greater than or equal to RECSIZ. 
Record area address may also be specified at GET/PUT 
time. 


YES 
RECREG Ve \ 


RECREG=YES indicates processing without a record area. 
When RECREG=YES, R1 contains the address of a logical 
input record that is available for processing after a GET or 
the address of the area that is available for construction of 
the next logical record before a PUT. If this parameter is 
omitted or if RECREG=NO, a record area (RECADR 
parameter) must be specified in the DEFSF or at 
GET/PUT time. 


(Optional) 


RECSIZ=n 


Indicates the record length (in bytes) for fixed length 
records. The keyword value gives an integer value of 18 
bytes through 32K bytes for magnetic tape and 7294 
bytes for disc. The maximum record length must be 
specified for variable length records. Record length does 
not include the header length. 


JF 
nectyP-{5} 


Specifies the record type, fixed (F) or variable (V) length, 
for the file. If omitted, records will be fixed length. 
If the file is assigned to cards or printer, the record 
type must be fixed. 


veriFy-{ve>} (Optional) 


NO 


VERIFY=YES states that a disc write verification will be 
done. If the file is not on disc, VERIFY is ignored. If 
omitted or VERIFY=NO, write verification is not used. 


Example 


OPERAND 


19 20. 2122.23.20 25 28 27 22728 29.30 31 32 33.34 35 36 37 98 39 40 Ay a2 43 4416 46 46, 


ied TIGERS! 22,00, ERROPT=, ERRCD.5. 
‘ecs! zeta, RELTIPAE 5 atk 4 arth 
aek FAQs 4.00 04 


Voces a Seas eaten ee A ek a, 


CARDIN is a sequential card file which is fixed length 
with block and record sizes of 80 bytes each. An error 
routine, ERRCD, processes any incorrect cards. 


DEFRF — Define Relative File 


The DEFRF macro defines relative files. The format for 
DEFRF is as follows: 


Name Operation Operand 


ident DEFRF access=}3| 


[BLKFAC=n] 
BLKSIZ=n 
ae 
[puFsHR- WN ] 
{[DATBUF1=symbolic address] 
_§YES 
[pareur2 ae. acaresst | 
symbolic address 
ERROPT=4S \ 
I 
KEYADR=symbolic address 
[RECADR=symbolic address] 


_SYES 
RECREG™} 
RECSIZ=n 
F 
RectyP-{—} 


[START=X] 
[END=Y] 


[veriry=jro {| 
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access-{8} 

Specifies sequential (S) or random (R) access mode. 
Together with the usage parameter of OPENL, it 
determines the processing environment of the file. If 
omitted, access is sequential. 


BLKFAC=n (Optional) 
Designates the number of records per block (blocking 
factor). The keyword value gives an integer value of 1 
through 255. When omitted, the blocking factor is 
determined by block size and record size. When BLKFAC 
is used, the relationship BLKSIZ2>BLKFAC(RECSIZ+4) 
must be true. 


BLKSIZ=n 


Specifies the block size of the file. The keyword value 
gives an integer value of 18 bytes through 32K bytes for 
magnetic tape and 7294 bytes for disc. The block size 
includes record headers for disc or tape files. 


_JYES : 
BUFSH ats \ (Optional) 


BUFSHR=YES indicates the !/O buffer(s) is(are) shared 
with another file. |}f BUFSHR=YES, the buffer address(es) 
must be explicitly specified and two bytes (one machine 
word) must be reserved immediately before DATBUF1. 
This word, containing zero, is used by OPENL and 
CLOSEL to resolve buffer usage conflicts. If 
BUFSHR=NO or if omitted, buffers are not shared, and 
OPENL and CLOSEL do not check for conflicts. 


DATBUF 1=symbolic address (Optional) 
Specifies the location of the first 1/O buffer, which must 
begin on an even byte boundary. If DATBUF1 is omitted, 
the buffer immediately follows the BDT. The buffer size 
must be greater than or equal to the block size of any file 
which uses the buffer. 
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DATBU F2n4 VES } (Optional) 


symbolic address 


Specifies a second !/O buffer, which allows overlapping of 
data transfer with information processing for sequential 
access. DATBUF2 is ignored for random access. If 
present, DATBUF2 must begin on an even byte boundary. 
DATBUF2=YES — generates the buffer following 
DATBUF1. If DATBUF2 is omitted, processing if from 
one buffer. 


symbolic address 
| (Optional) 


eRROPT) S 
I 


Specifies one of three conditions for processing errors. 
The symbolic address gives the user control when errors 
occur. The skip (S) option and ignore (1) option, for input 
files, skips to the next block or ignores errors, 
respectively, and processing continues. S is illegal for 
random access. If ERROPT is omitted, error conditions 
abort the job. 


KEY ADR=symbolic address 


Gives (for random access) the address of the location that 
will contain the number of the record to be processed. 
KEYADR is ignored for sequential access. The symbolic 
adaress for KEYADR is a 4-byte location beginning on an 
even byte boundary. 


RECAD R=symbolic address (Optional) 


Specifies the address of the record area. Record areas may 
also be specified at GET/PUT time. They are required for 
random output to a blocked file. The size of the record 
area must be greater than or equal to RECSIZ. 


RECR ec={vest 


NO (Optional) 


RECREG=YES defines processing without a record area. 
When RECREG=YES, R11 contains the address of a logical 
input record that is available for processing after a GET or 
the address of the area that is available for constructing 
the next record before a PUT. If RECREG is omitted or if 
RECREG=NO, a record area must be defined either in the 
DEFRF macro at GET/PUT time. If random output is 
selected with RECREG=YES, the blocking factor must 
equal one. 


RECSIZ=n 


Indicates the record length (in bytes) for fixed length 
records. The keyword value gives an integer value of 18 
bytes through 32K bytes for magnetic tape and 7294 
bytes for disc. For variable length records, the record 
length is the maximum record length permitted. Record 
length does not include the header length. 


Se 
nectyP-El 


Denotes the record type, fixed (F) or variable (V) length, 
of the file. The default value is fixed length. 


START=X (Optional) 


States the logical limit, which may range from 1 to 232.4 
(decimal), for the beginning of processing. At creation, 
this limit becomes the permanent offset for relative 
addressing. If START is used, the END parameter must 
also be used. 


END=Y (Optional) 
States the logical limit for ending processing, where Y2X. 
(X is the START parameter limit.) Limits are decimal 
numbers. 


YES 
VERIFY=| Ve } 


VERIFY=YES states that a disc write verification will be 
done. If omitted or VERIFY=NO, write verification is not 
used. 


(Optional) 


Example 


OPERAND 


19 20 21 22.23 26 25 26 27,28 29 3 0 31 2 33.34 35 3637 38.99 40,41 42,4 43.44 45 a6 


ROCESS=R, OLKS PEERY Vem 
| WEY ADRE KEY IS, RECS /.22 400.45 3 
eee ey sake aenean 2 


a a ar ee oe 


MPLOY is a relatively organized file which allows random 
access through a key name, KEYIS. Although the fixed 
length record size is 100 bytes, the block size is 104 
bytes, which includes the record header. Write verification 
is specified. 


DEFIF — Define Indexed File 


The DEFIF macro defines indexed files. The format for 
DEFIF is as follows: 


Name Operation Operand 


ident DEFIF access-|$ 


[BLKFAC=n] 
BLKSIZ=n 


[sursun-| a 


[DATBUF1=symbolic address] 
DATBUF2= ll ta anne) | 


ERROPT-| jure nacre 


YES : 
[inoBuF- tale address | 


[inosHR= es | 


INDSIZ=n 

' {INMAIN=symbolic address] 
KEYADR1=symbolic address 
{KEYADR2=symbolic address] 


KEYSIZ=n 
[RECADR=symbolic address] 
_(YES 
[Recrec-|*F 
RECSIZ=n 
_JYES 
[veriry-{¥e 4 
access-{S 


Specifies sequential (S) or random (R) access mode. 
Together with the usage parameter specified in the 
OPENL macro, this parameter determines the processing 
environment of the file. If omitted, processing is. 
sequential. . 


BLKFAC=n (Optional) 
Indicates the number of records per block (blocking 
factor). The keyword value gives an integer value of 1 
through 255. When not specified, the blocking factor is 
determined by the block size and record size. When 
BLKFAC is used, the relationship BLKSIZZ>BLKFAC 
(RECSIZ+4) must be true. 


BLKSIZ=n 


Specifies the block size of the file. The keyword value is 
in integer value of 18 bytes through 7294 bytes for disc. 
BLKSIZ must include the space for record headers. 
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BUFSH r4Noe (Optional) 


NO | 
BUFSHR=YES specifies that the I/O buffer is shared with 
another file. If BUFSHR=YES, the buffer address must 
have been explicitly specified and one word immediately 
before DATBUF1 must be reserved. This word contains 
zero and is used by OPENL and CLOSEL to resolve buffer 
usage conflicts. If omitted or BUFSHR=NO, buffers are 
not shared, and OPENL and CLOSEL do not check for 
conflicts. 


DATBUF 1=symbolic address (Optional) 
Designates the address of the first 1/O buffer, which must 
begin on an even byte boundary. The buffer size must be 
greater than or equal to BLKS!Z when the user generates 
his own buffer. 1f DATBUF1 is omitted, a buffer is 
generated following the BDT. 


(Optional) 


symbolic address 
YES 


DATBUF2-4 


Specifies a second 1/O buffer, which permits overlapping 
of data transfer with record processing. If present, 
DATBUF2 must begin on an even byte boundary. 
DATBUF2=YES generates the buffer following 
DATBUF1. If DATBUF2 is omitted, processing is from 
one buffer. 


symbolic se (Optional) 


ERROPT={ 


Specifies one of the two conditions for processing errors. 
The symbolic address gives the user control when errors 
occur. The ignore (I) option, only for input files, ignores 
errors and processing continues. If ERROPT is not 
specified, error conditions abort the job. 


inDBUF~\ ES \ (Optional) 


symbolic address 


Specifies the address of a buffer to be used by the system 
for processing of index blocks. If this parameter is 
omitted for random access, INDSHR=YES must be 
specified. INDBUF=YES causes automatic buffer 
generation. 
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INDSH Roy 


NO (Optional) 


INDSHR=YES indicates that the index buffer is shared 
with the data file buffer. Access must be random, 
DATBUF1 must be specified, and RECREG must not be 
specified. If omitted or INDSHR=NO, no index buffer 
sharing occurs. 


INDSIZ=n 


Specifies the index block size. The value n ranges from 18 
bytes to 7294 bytes. 


INMAIN=symbolic address (Optional) 
Specifies the address in main storage where the directory 
to the directory index entries are read into from mass 
storage. This option expedites random processing. For 
sequential access, this parameter is ignored. 


KEYADR 1=symbolic name 


Specifies the address of the location containing the primary 
key value of a record to be: 


1. Updated, retrieved, added, or deleted when 
in random mode 


2. Updated, added, or deleted when in sequen- 
tial mode 


KEYADR1 is required for record addition in sequential 
mode, optional for update in sequential mode, and 
ignored for input only in sequential mode. It is required 
for access in random mode. 


KEYADR2=symbolic address (Optional) 
Specifies the address of the location which contains the 
primary key value of the record after a GET (forward 
key) that will be obtained on the next GET. When the end 
of file is reached, the first two bytes of the location 
specified by KEYADR2 will be set to FFFF 46 to indicate 
an EOF. This allows records to be added at the end of the 
file. KEYADR2 is optional for sequential access and 
ignored for random access. 


KEYSIZ=n 


Specifies the length (in bytes) of the primary key. The 
value n ranges from 2 to 100 bytes. 


RECADR=symbolic address (Optional) 


Specifies the address of a record area. The record area size 


must be greater than or equal to RECSIZ. It is required - 


for random output to a blocked file using PUT. Record 
areas may also be specified at GET/PUT time. 


RECR cone t (Optional) - 


NO 


RECREG=YES specifies processing without a record area. 
When RECREG=YES, R1 contains the address of a logical 
input record after a GET or the address available for 
constructing the next record before PUT or PUTU. If 
omitted or RECREG=NO, a record area must be specified 
either in the DEFIF macro or at GET/PUT time. Table 
6-1 indicates when RECREG may be used. 


Table 6-1. RECREG Use 


Access Update Output 
Sequential Any BLKFAC | BLKFAC Any BLKFAC 
of 1 
Random Any BLKFAC | BLKFAC ieee 
of 1 


RECSIZ=n 


Specifies the fixed record length in bytes. The value n 
ranges from 18 bytes to 7294 bytes. The record length 
does not include the header length. 


VERI Fue 


NO 


VERIFY=YES states that a disc write verification will be 
done. If omitted or VERIFY=NO, no write verification is 
done. 


Example 


OPERATION OPERAND 


19 20 2 22 23 4 252 26 228, 28 29 “30 31 32 3 3435, 36,37 38 39 40.41 42 43 44 45 46 
ACCESS=R,BLKSIZ=94,° ; 
| ERROPTeMISTAK, VERIFYS FVES 3 
KEVADRL™KEYNAM, RECS! Z= ee 
tLe gcrieaces eee yan 


PARTLST is an indexed file open for random access 
through KEYNAM. The keysize is five bytes. The block 
size is 94 which is the record size plus four bytes for the 
control header. The index block size is 250 bytes. If an 
error is detected, the error routine MISTAK receives 
control. A write verification will be done. 


Summary of File Definition Parameters 


Table 6-2 summarizes the parameters for sequential, 
relative, and indexed files. 


DEFLB — Define Label 


The DEFLB macro generates file label data into a 
main-storage buffer for creating and checking disc labels. 
The logical 1/O level file control macros may use DEFLB, 
but it is not necessary to define labels at the logical !/O 
level. The format for DEFLB is as follows: 


Name Operation Operand 


FILENAM=name 
[MSC=code] 


labadr DEFLB 


FILENAM=name 


Specifies a 1- to 17-character alphanumeric file name. The 
first character may be A-Z, 0-9, or $. Imbedded dashes are 
allowed, but not imbedded blanks. Index file names are 
created by adding an asterisk at the end of the associated | 
data file name. 


MSC=code (Optional) 


Designates a 4-byte EBCDIC modification security code, 
which is used only for work and permanent files. If 
omitted, blanks are assumed. 


Example 


TAPE1 gives the label identification for a file named 
PAYROLL. 
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Table 6-2. Filo Definition Parameters 
File 
Type 


Relative indexed 


Parameter Sequential 


ACCESS Required; Required; 
default default 
sequentia sequential 

BINARY Optional Pepe 

for card 
devices 

BLKFAC Optional; Optional Optional 

default is 
‘| packing 
BLKSIZ ~ Required.’ 


“> Required .| Required. 
BUFSHR Optional Optional Optional 


DATBUFi1 Optional; Optional; Optional; 
default default default 
follows follows 
BOT BDT 

DATBUF2 Optional 


follows 
BDT 
END Optional 
ERROPT Optional Optional 
INDBUF 


Required 
INMAIN 


Optional 


for 
sequential 
access 


Optional 


Required 


Optional 


KEYADR(1) Required Required 
for ran- for ran- 
dom access} dom access, 

sequential 
update, 
sequential 


output 


KEYADR2 
KEYSIZ 


LABTYP 
only 
RECADR Optional 
Optional 
PRecsz | 


Optional 


Required 


Optional Optional 


Optional Optional 


Required | Reauired | Required 


RECTYP Required; Required; Fixed 
default default } length 
fixed fixed 


Optional 


START : 


Optional Opiional 


LOGICAL 1/O FILE CONTROL MACROS 


The file control macros (OPENL, CLOSEL, and CLOVEL) 
direct data transmission at the logical !/O level. 


The functions of the OPENL macro are as follows: 


e Opens the file for data transmission by 
establishing an FDT 


e Records BDT entries not supplied by DEFSF, 
DEFRF, or DEFIF 


e@ Catalogs logical level file attributes when 
files are opened for output for the first 
time 


e Checks file attributes supplied through 
DEFSF, DEFRF, or DEFIF against perman- 
ent cataloged attributes on subsequent opens 


e  Prefills buffers for sequential access by GET/ 
PUT requests 


The CLOSEL macro closes files to data transmission and 
empties buffers for GET/PUT when required. 


The CLOVEL macro closes disc or magnetic tape volumes 
and switches to the next volume before the end of the 
allocated disc space or end of tape marker is reached. 
End of allocated area volume switching is performed 
by the GET/PUT logic through the CLOVEL macro. 


OPENL — Open Logical File 


The OPENL macro opens a file for logical 1/O processing. 
The format for OPENL is as follows: 


Name Operation Operand 
{tag] OPENL IDENT=name 
_ {ANS { 
[contro Jans vet 


‘[LABDEF=symbolic address] 


[uisr=|x5°f] 


IR EWI no- er t| 


font 


IDENT=name 


Specifies the file identifier. It must correspond to the 
name field (file identifier) of a DEFSF, DEFRF, or 
DEFIF macro. 


ANS (Optional) 


CONTROL AA ve 


CONT ROL=NATIVE indicates that the control characters 
are native to that device. ANSI control characters are used 
if omitted or CONTROL=ANS, 


LABDEF=symbolic address (Optional) 
Specifies the address of the main-storage buffer that 
contains a file label. The symbolic address should be 
identical to that specified in the label address name field 
of a DEFLB macro. For disc files, label information may 
have been specified by Control Language //DEFINE 
statements which override LABDEF information if both 
are present. This parameter may not be used for 
permanent files or work files with update or output usage. 
For temporary or scratch files, the filename is 
concatenated with the job name. It is ignored for files 
assigned to unit record devices or magnetic tape. 


YES 
List-{6 \ 


If LIST=YES, only the parameter packet is generated. If 
LIST=NO, only the subroutine linkage is generated and 
loading of general-purpose register 6 (R6) with the address 
of the parameter packet and general-purpose register 7 
(R7) with the save area address is a user responsibility. If 
the LIST parameter is omitted, both the subroutine 
linkage and the parameter packet are generated 
immediately following the subroutine call; and the user 
must load R7 with the save area address. A detailed 
discussion of the LIST parameter is contained in 
Appendix A. 


(Optional) 


(Optional) 


YES 
NO 


REWIND=\*E° 


REWIND=NO specifies that no initial rewind will be 
performed. This parameter is ignored for non-tape files. If 
REWIND=YES or if omitted, initial rewind is performed. 


USAGE= ut ; (Optional) 


O 


Determines input, update, or output processing. Update 
usage is allowed for sequential files only if the record type 
is fixed length and the file is assigned to mass storage. The 
default value is |. 


Example 


OPENL opens the input file CARDIN for processing. 


CLOSEL — Close Logical File 


The CLOSEL macro closes a file to logical 1/O processing. 
The format for CLOSEL is as follows: 


Name Operation Operand 


{tag] CLOSEL IDENT=name 


_{YES 
List={¥6 q 
_SYES 
Lock=}\5 
YES 


REwIND=} <5 


iDENT=name 


Specifies the file identifier. 


_{YES 
List-\Ne \ 


lf LIST=YES, only the parameter packet is generated. If 
LIST=NO, only the subroutine linkage is generated and 
loading of R6 with the address of the parameter packet 
and R7 with the save area address is a user responsibility. 
lf the LIST parameter is omitted, both the subroutine 
linkage and the parameter packet are generated 
immediately following the subroutine call; and the user 
must load R7 with the save area address. A detailed 
discussion of the LIST parameter is contained in 
Appendix A. 


. (Optional) 
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Look-{xet (Optional) 


Indicates the disposition of the file. When the parameter is 
not specified or LOCK=NO, the file may be reopened 
from within the same job; tape files are rewound. When 
LOCK=YES, OPENL may not be executed again during 
the same job; tape files are unloaded. 


YES 


newino-{XEs (Optional) 


NO 


REWIND=NO specifies that no rewind will be performed 
after closing the file. This parameter is ignored for 
non-tape files. If REWIND=YES or if omitted, initial 
rewind is performed. 


Example 


OPERAND 


12-34 5 67 B{9[ 10 11 1213 14 15 1617 


| 18 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 9837 3839 49 41 42 4344 45 46 


CLOSEL closes the file MPLOY to any further proc- 
essing. 


CLOVEL — Volume Switching 


The CLOVEL macro performs volume switching. It is 
used for sequential multivolume files assigned to tape or 
disc and should be used only to prematurely close a 
volume and switch to the next sequential volume. Volume 
switching at EOV is performed automatically by the 
GET/PUT modules. 


CLOVEL performs header and trailer label processing on 
tapes, alternate unit processing on tapes, and disc pack 
mounting and demounting (via operator control). The 
format for CLOVEL is as follows: 


Name Operation Operand 


IDENT=name 


[ust 1 a q 


[tag] CLOVEL 


IDENT=name 


Specifies the file identifier. 
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List| No} (Optional) 
if LIST=YES, only the parameter packet is generated. If 
LIST=NO, only the subroutine linkage is generated and 
loading of R6 with the address of the parameter packet 
and R7 with the save area address is a user responsibility. 
lf the LIST parameter is omitted, both the subroutine 
linkage and the parameter packet are generated 
immediately following the subroutine call; and the user 
must load R7 with the save area address. A detailed 
discussion of the LIST parameter is contained in 
Appendix A. 


Example 


1.73.4 8 8 7. B49] 10 14 12 19 14 15 16 17] 18 19 20 21 22,29 24 25, 26 27 28 29.30 41 32 93 34 36 36 97 30.99 4041 42 42M 95 48 


DENT*TAPFIL................- 


FEY Can ee One En OE WOOT Oe OO Ta i San Wee nn ene On We er De 


CLOVEL switches volumes in a multivolume file called 
TAPFIL. 


DATA TRANSMISSION MACROS 


The data transmission macros — GET, PUT, and associated 
macros — control the transmission of data to and from 
the different files. 


Table 6-3 lists the GET/PUT macros allowed according to 
file type and usage. 


GET — Get Record 


The GET macro makes a logical record available in a 
record area. When no record area is present, the address 
of an available logical record in an !/O buffer is pro- 
vided in R1. The format for GET is as follows: 


Name Operation Operand 
[tag] GET IDXSA=YES 
IDENT=name 


[uist=4 vt] 


[RECADR=symbolic address] 
[RECS1Z=symbolic address] 
{RTNADR=symbolic address] 


Table 6-3. GET/PUT Macro Usage 


Macro 


GET ;} PUT | LOCRC | PUTU 


Sequential 


Input 
Update 
Output 


Relative 


Indexed 


input 
Update 
Output 


IDXSA=YES 


Specifies sequential processing of indexed files; it is 
ignored for random processing. If IDXSA is omitted for 
sequential processing, contro! is given to the user’s error 
routine or the job aborts. 


IDENT=name 


Specifies the file identifier. 


_JYES F 
List-{X6 \ (Optional) 


If LIST=YES, only the parameter packet is generated. If 


LIST=NO, only the subroutine linkage is generated and 
loading of R6 with the address of the parameter packet 
and R7 with the save area address is a user responsibility. 
If the LIST parameter is omitted, both the subroutine 
linkage and the parameter packet are generated 
immediately following the subroutine call; and the user 
must load R7 with the save area address. A detailed 
discussion of the LIST parameter is contained in 
Appendix A. 


RECADR=symbolic address (Optional) 
Specifies the address of a record area. When RECADR is 
present in the GET macro, it overrides any RECADR 
specified ina DEFSF, DEFRF, or DEFIF macro. 


x 

X 
Input 4 
Update xX 4 
Output » 4 ».4 

xX 

Xx 


RECSIZ=symbolic address (Optional) 
Specifies the address of a location that will contain the 
size (in bytes) of the logical record upon return. RECSIZ 
is ignored for fixed length records. It must specify an 
even byte boundary. 


RTNADR=symbolic address (Optional) 
Specifies the address of a user routine which receives 
control when a sequentially processed file reaches the end 
of file or a randomly processed file contains an invalid key 
value in the KEYADR1 address. When RTNADR is 
omitted, contro! is given to the error option selected in 
the ERROPT parameter of the define macro. If no 
ERROPT was specified, the job will abort. 


Example 


OPERATION OPEAAND 


123456 7,8 


‘WW, U1 12 13 14 18 16 17} 18] 19 20, 21 22 23 24 26, 26 27 28 29 40 31 32 33 34, 36, 36 37, 38-99 40,41 02 43.44 45,46 
IDENT=CARDIN, RTNADRADONE .., 
Nae teed es PORES Ver te eer eee are aOR Te te ere a 


The GET macro reads the CARDIN file until the DONE 
parameter is satisfied. 


PUT — Put Record 


The PUT macro moves a logical record from a record area 
into an 1/O buffer or indicates that a logical record has 
been generated by the user in an !/O buffer. PUT is used 
to update records for sequential and relative files. The 
format for PUT is as follows: 


Name Operation Operand 
IDXSA=YES 
IDENT=name 


[ ust} Medd 


[RECADR=symbolic address] 
[RECS!tZ=symbolic address] 
[RTNADR=symbolic address] 


[tag] PUT 


IDXSA=YES 


Specifies sequential processing of indexed files; it is 
ignored for random processing. If |IDXSA is omitted for 
sequential processing, control is given to the user’s error 
routine or the job aborts. 


IDENT=name 


Specifies the file identifier. 


_JYES , 
List-{VE \ (Optional) 


If LIST=YES, only the parameter packet is generated. If 
LIST=NO, only the subroutine linkage is generated and 
loading of R6 with the address of the parameter packet 
and R7 with the save area address is a user responsibility. 
lf the LIST parameter is omitted, both the subroutine 
linkage and the parameter packet are generated 
immediately following the subroutine call; and the user 
must load R7 with the save area address. A detailed 
discussion of the LIST parameter is contained in 
Appendix A. 


RECADR=symbolic address (Optional) 


Specifies the address of a record area. When RECADR is 


present in the PUT macro, it overrides any RECADR 
specification in a DEFSF, DEFRF, or DEFIF macro. 


6-12 


RECSIZ=symbolic address 


Specifies the address of a location that contains the size 
{in bytes) of the logical record. RECSIZ must specify 
an even byte boundary. It is ignored for fixed length 
records. When RECSIZ is absent and the records are 
of variable length, control is given to ERROPT or the 
jot aborts. 


RTNADR=symbolic address (Optional) 
Specifies the address of a user routine which receives 
control when the end of allocation or a key error 
occurs. When RTNADR is not defined, control goes to 
the addresses specified in the ERROPT parameter of the 
define macro. !f ERROPT was not specified, the job aborts. 


Example 


The PUT macro writes the file RECRD according to the 
byte size found in SIZE. 


SETL — Set Limits 


The SETL macro establishes an initial key value for 
sequential access of indexed files. If SETL is not issued, 
retrieval starts at the logical beginning of the file. The 
format for SETL is as'follows: 


Name Operation Operand 
[tag] SETL IDENT=name 
KEYERR=symbolic address 
_ fves | 
[uist- he 
KEY 
srant={cxey t 
BOF 
IDENT=name 


Specifies the file identifier. 


KE YERR=symbolic address 


Specifies the address which receives control when START= 
KEY and there is no key value specified. This parameter 
is required for START=KEY;; otherwise, it is ignored. 


YES 
LIsT-{No \ 


if LIST=YES, only the parameter packet is generated. If 
LIST=NO, only the subroutine linkage is generated and 
loading of R6 with the address of the parameter packet 
and R7 with the save area address is a user responsibility. 
lf the LIST parameter is omitted, both the subroutine 
linkage and the parameter packet are generated 
immediately following the subroutine call; and the user 
must load R7 with the save area address. A detailed 
discussion of the LIST parameter is contained in 


Appendix A. 
KEY )- 

START= CKEY 
BOF 


Determines where the retrieval begins according to the 
following codes. 


Code Option 


KEY Retrieval begins with the record having 
the key value contained in KEYADR2 
of the tagged DEFIF macro. If no data 
record with this key exists, control 
returns to KEYERR. 

GKEY Retrieval begins with the record having 
the key value contained in KEYADR2, 
or if no record having this value exists, 
it begins with the record having the next 
greater value. If no record has a greater 
key value, KEYADR2 receives FFFF 46: 
indicating the end of the file. This per- 
mits records to be added to the end of 
the file. 

BOF Retrieval begins at the beginning of the 
file. 


Example 


ae cli Seam S PERE RERS eh near haba beer hen heehee A 
1234667 40 Uf 12.13 14, 15 16 17} 18] 19 20, 21 22 23 24 26 26 27 28 29 30 31 32,33 34 35 36 37 38.39 40 41 41 42 43.44 45 48 


TOEA jouer. ae Pearere 


a a, SO aE nO SOO et OT SO nn RS OE ee SE Se 


The SETL macro is used with a GET to establish the 
beginning key value for indexed files. In this case, re- 
trieval will begin at the beginning ds the file named 
PRTLST. 


(Optional) 


LOCRC — Locate Record 


LOCRC is a relative record seek macro. A seek operation 
is issued to the block containing the record number found 
in the location specified by the KEYADR parameter of 
the DEFRF macro. LOCRC is used to overlap seek and 
processing time for random access. If an error condition 
arises, the following GET/PUT receives the status by 
having control returned to the invalid key routine. The 
format for LOCRC is as follows: 


Name Operation Operand 


IDENT=name 


[ust-} ho] 


[tag]  LOCRC 


IDENT=name 


Specifies the file identifier. 


_JYES 
List={6 \ (Optional) 


If LIST=YES, only the parameter packet is generated. If 
LIST=NO, only the subroutine linkage is generated and 
loading of R6 with the address of the parameter packet 
and R7 with the save area address is a user responsibility. 
lf the LIST parameter is omitted, both the subroutine 
linkage and the parameter packet are generated 
immediately following the subroutine call; and the user 
must load R7 with the save area address. A detailed 
discussion of the LIST parameter is contained in 
Appendix A. 


Example 


The LOCRC macro positions the access mechanism at the 
location on the disc file which contains the record. 
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hae 


ne ele FOES OT RE Yee WA rel WE ee 


PUTU — Put Update 


The PUTU macro updates a record in indexed files and 
rewrites the record retrieved by the preceding GET. The 
address specified by KEYADR in the DEFIF macro 
must contain the key value of the record to be changed. 
If the key value in KEYADR is not identical to the 
key value of the record obtained in the previous GET, 
control goes to the invalid key routine. The format for 
PUTU is as follows: 


Name Operation Operand 


[tag] PUTU {DENT=name 


KEY ERR=symbolic address 


[ust-}h0 1] 


[RECADR=symbolic address] 


IDENT=name 


Specifies the file identifier. 


KEYERR=symbolic address 


Specifies the address which will receive control when a 
key error occurs. 


_{YES 
LIST te \ 


if LIST=YES, only the parameter packet is generated. If 
LIST=NO, only the subroutine linkage is generated and 
loading of R6 with the address of the parameter packet 
and R7 with the save area address is a user responsibility. 
If the LIST parameter is omitted, both the subroutine 
linkage and the parameter packet are generated 
immediately following the subroutine call; and the user 
must load R7 with the save area address. A detailed 
discussion of the LIST parameter is contained in 
Appendix A. 


(Optional) 


RECADR=symbolic address (Optional) 


Specifies the address of a record area. When RECADR is 


present in the PUTU macro, it overrides RECADR 
specified in a DEFIF macro. 
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Example 


: OPERATION OFERAND 2 
10, 11, 12.13 14 16 16, 17) 18] 19 20 21 22 23 24 75,26 27 28 29 30 31 32 39 24 35 30.97 38.39 A0 41 AZ 43 44 45 46 
le 


PUTu.. T?RECRO, KEYERRsHERETS.. 


Se ar a ee ae a SO EY 


PUTU updates a record in the RECRD file. HEREIS 
receives control if the key from the file is invalid. 


DELR — Delete Record 


The DELR macro deletes a record from an indexed file. 
The indexing information is deleted from the file’s 
associated index blocks (and directory blocks if 
necessary), and the data record is left unchanged. Proc- 
essing requirements differ depending upon access. 


Sequential access requires that the key value contained 
in KEYADR of the DEFIF macro be equal to the key 
value of the record obtained on the previous GET. If 
it is not equal, contro! goes to the invalid key routine. 


Random access does not require a preceding GET. If a 
record having the key value contained in KEYADR does 
not exist, control goes to the invalid key routine. The 
format for DELR is as follows: 


Name Operation Operand 


IDENT=name 
KEY ERR=symbolic address 


[ust= 1 t] 


{tag} DELR 


IDENT=name 


Specifies the file identifier. 


KEYERR=symbolic address 


Specifies the address which will receive control when a 
key error occurs. 


_fYES . 
LisT=1N6 \ (Optional) 
If LIST=YES, only the parameter packet is generated. If 
LIST=NO, only the subroutine linkage is generated and 
loading of R6 with the address of the parameter packet 
and R7 with the save area address is a user responsibility. 


If the LIST parameter is omitted, both the subroutine 
linkage and the parameter packet are. generated 
immediately following the subroutine call; and the user 
must load R7 with the save area address. A detailed 
discussion of the LIST parameter is contained in 
Appendix A. 


Example 


IT=RECRD, KEYER*URONS, | 


deh lhe Acne ae he el a enema a oe Bee allem 


DELR deletes a given record from the indexed file RECRD. 
WRONG is the routine that handles key errors. 


CONSOLE COMMUNICATION MACROS 


Two macros, CONSOLE (an active macro) and MESSAGE 
(a data macro), are available for communicating with 
the operator’s console. 


CONSOLE — TRANSMIT MESSAGE TO CONSOLE AND 
OPTIONALLY RECEIVE REPLY 


The CONSOLE macro enables programs to transmit 
messages to the operator's console and optionally re- 
ceive replies. The main-storage format of the message 
to be sent to the console must include two fields, a 
control block which is not typed and the text field 
which contains the actual message. The buffer set up 
to receive a reply from the console (if any) must contain 
a control block followed by the actual buffer for the 
reply text. The format of CONSOLE is as follows: 


Name Operation Operand 


[tag] CONSOLE DATBUF1symbolic address 


[DATBUF2=symbolic address] 
DATBUF1=symbolic address 
Specifies the address of the message control block which 


is followed by the message text. 


DATBUF2=symbolic address (Optional) 


Specifies the address of the reply control block which is 
followed by the reply buffer area. 
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Example 


NAME OPERATION 
12345678 To 11 12 13 14 15 16 17 


TYPE | feonsoLe DAT GUFL=LAGELA, >. . 
eet ase —. | (DAT.AUE.22.CABERS 


OPERAND 


19 20. 21.22 23-24 25 26 27 28. 29 0 3) 32 33 34 35 36 37 38 39. 40.41 42 43.44.45 46 


The message located in the message area, LABELA, is 
transmitted to the console. When it is received, the 
reply is stored in the reply area, LABELB. 


MESSAGE — SET UP MESSAGE FORMAT 


The MESSAGE macro, to. be used in conjunction with 
the CONSOLE macro, simplifies the generation of messages 
by creating the correct format required by CONSOLE. 
A tag is required for all MESSAGE macros so that the 
corresponding CONSOLE macro may locate it. Two for- 
mats exist for the MESSAGE macro, one for generating 
an output message and one for generating a reply buffer. 


Generation of an Output Message 


The format for generating an output message is as 
follows: 
Name 


Operation Operand 


tag MESSAGE [DATBUF1=symbolic address] i 
eae cas number 


DATATXT=character string 


[move-{£t ] 


DATBUF1=symbolic address (Optional) 


Enables a name to be attached to the beginning of the 
message text field. 


DATSIZ1=decimal number 


Specifies the decimal length (in bytes) of the message 


text. If no length is specified, the text length will be used. 
If there is no message, a length of zero is assumed. The 
maximum value of DATSIZ1 is 100. 
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DATAT XT=character string 


Specifies the actual message to be placed in the message 
text field. It is created in EBCDIC and may be up to 100 
characters (bytes) long. The default is a string of blanks, 
with length being determined by the parameter DATSIZ1. 
The character string must be coded in the form, C’message 
text’. 


ooo 


Specifies whether the message is informative (I) or . 
directive (D). MODE=D indicates that the message calls 
for some operator action. The default value of MODE is I. 


(Optional) 


OPERAND 


LZL2 20, ee fe 
pater TXT#.¢! ae ‘ERROR’... 


Creates a message area at assembly time consisting of a 
message control block, LABELA, followed by a message 
text area, LABELC. The message text area will be 
20 bytes long. The first 12 bytes will contain FORMAT 
ERROR and the remaining eight bytes will contain 
blanks. 


Generation of a Reply Buffer 


The format for generating a reply buffer is as follows: 
Name Operation Operand 


[DATBUF2=symbolic address] 
DATSIZ2=decima! number 


tag MESSAGE 


DATBUF2=symbolic address (Optional) 


Enables a name to be attached to the beginning of the 
reply text field. 


6-16 


DATSIZ2=decimal number 


Specifies the decimal length in characters (bytes) of the 
reply buffer to be generated. The reply field will be 
assembled with blanks. The maximum value of DATSIZ2 
is 100. 


Example 


om) 


OPERATION OPERAND 
10 11 1213 14 15 16 il 19,20, 21, 22,23 24 26 26,27 26 29 30, 31, 32,93. 34 95, 36,37, 30 39 40,41, 42 43,44 05,26 
f 


i Pars. Z2.2.20.. aa 


Creates a reply area at assembly time consisting of a 
reply control block, LABELD, followed by a 20-byte 
reply text buffer, LABELD. 


CONTROL PROGRAM SERVICES MACROS 


Control Program Services macros are those macros which 
are implemented directly by the Control Program itself. 
These macros include: 


e@ Program Termination 


HALT 
EHALT 
ABEND 


@ Time and Date 
TIME 


SDATE 
JDATE 


PROGRAM TERMINATION MACROS 


Three macros are provided for program termination, 
HALT for normal step termination, EHALT for step and 
job termination, and ABEND for abnormal termination. 


HALT — Terminate Program 


The HALT macro is used to perform normal termination 
of a user’s program step. This macro will not result in a 
memory dump unless DUMP=YES has been coded in the 
/[EXECUTE statement associated with the program. The 
format for HALT is as follows: 


Name Operation 


[tag] HALT 


EHALT — Terminate Program 


The EHALT (error halt) macro is used to request 
termination of a user’s job. This macro will not 
automatically give a memory dump unless DUMP=YES 
has been coded in the //EXECUTE statement associated 
with the program. The format for EHALT is as follows: 


Name Operation 
[tag] EHALT 


ABEND — Terminate Program Abnormally 


The ABEND macro is used to request abnormal 
termination of a job, and to pass a completion code to 
Job Monitor for display. A dump will be given unless 
DUMP=NO is specified on the //EXECUTE statement. 
The completion code is a 16-bit binary value. The format 
for ABEND is as follows: 


Name Operation Operand 


[tag] ABEND INFOADR=symbolic address 
INFOADR=symbolic address 


Specifies the first byte address of the area containing the 
completion code. 


TIME AND DATE MACROS 


The time and date of program execution may be obtained 
from the system with the TIME and SDATE macros. 


A third macro, JDATE, is available for obtaining a. 


special user-specified job date. 


TIME — Retrieve Time of Day* 


The TIME macro returns the current time of day in the 
operand specified. The time of day is returned in an 
‘unpacked decimal format: hhmmss, where hh is the 
hour, mm is the minute, and ss is the second. The format 
for TIME is as follows: 


Name Operation Operand 


[tag] TIME INFOADR=symbolic address 


iINFOADR=symbolic address 


Specifies the first byte address of the area which receives 
the time. 


Example 


PS Sane SORT RRS UE Uy NOB En ES CS 


Transfers the current time (six bytes) to the memory lo- 


cation labeled CLOCK. 


SDATE — Retrieve System Date 


The SDATE (system date) macro returns the system date 
in the operand specified. The date is returned in one of 
two unpacked decimal formats: mmddyy or yyjjj, - 
where mm is the month, dd is the day, yy is the year, 
and jjj is the Julian day. The format for SDATE is as 
follows: 


Name Operation Operand 
tag SDATE INFOADR=symbolic address 
- ri 
MODE= r 


IN FOADR=symbolic address 


Specifies the first byte address of the area that receives 
the date. 


*Function is available on minimal system (16K storage), but 
returns zeros, 
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Specifies the current date in the calendar (C) 6-byte 
format mmddyy or the Julian (U) 5-byte format yyjjj. 
The default value is C. 


Example 


ORDTI EROSION 
[INFOADR* DATE’, MODE*@ 
Transfers the system date, in calendar format, to the 
memory location labeled DATE1. 


JDATE — Retrieve Job Date 


The JDATE (job date) macro returns the date provided 
for by a //SET statement. The date returned will be the 
system date unless the //SET statement has specified 
a job date. The date is returned in one of two unpacked 
decimal formats: mmddyy or yyjij, where mm is the month, 
dd is the day, yy is the year, and jjj is the Julian day. 
The format for JDATE is as follows: 


Name Operation Operand 
tag JDATE INFOADR=symbolic address 
MODE= sf 


INFOADR=symbolic address 


Specifies the first byte address of the area which re- 
ceives the date. 


= 
mone-{<\ 


Specifies the current date in the calendar (C) 6-byte 
format mmddyy or Julian (J) 5-bit format yyjjj. The 
default value is C. 


Example 


OPER AID 


18 20 2t 22.23 24 26 20 27 28 29.90 3) 32 19 34 35 3637 9830 40.41 42 49.46 05 08 
32, 33,4, 98, 6 37, 3898, 40, 4 42 09.06 05, 
JINFOAOR=DATE?,MODE*J... 


otk Bo eed ede he a 


Transfers the job date, in Julian format, to the memory 
location labeled DATE2. 
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The LIST parameter, which is used by the logical 1/O 
level file control macros and the GET/PUT macros, 
allows for separate generation of the parameter packet 
and the subroutine linkage. 


All logical 1/O level requests perform a subroutine call 
to either the GET/PUT module or the Data Management 
Open Close Control (DMOCC) using the following linkage 
conventions. 


1. Parameter list address set in general-purpose 
‘ register 6 (R6) 


2. Save area address set in general-purpose 
register 7 (R7) 


BDT Address (GET/PUT Macros) or DMOCC (OPENL/CLOSEL Macros) 


A. LIST PARAMETER 


2 List=]VES 
NO 


The LIST parameter is used to generate parameter packets 
and subroutine linkages which make it possible to run 
program subroutines at execution time. The LIST=YES 
option generates the parameter packet, and the LIST=NO 
option generates the subroutine linkage. (Tables A-1 
and A-2, at the end of this appendix, provide complete 
descriptions of the parameter packets for the GET/PUT 
and OPENL/CLOSEL macros.) 


When the LIST=NO option is specified, the IDENT 


- parameter must be specified for the GET/PUT macros. 


Prior to issuing the LIST=NO option, the user must load 


- R6 with the address of the appropriate parameter packet 


(generated by the LIST=YES option) to be used and must 
load R7 with the save area address. Together the address 
of the parameter packet and the subroutine linkage will 
take the program to the appropriate subroutine at 
execution time. When a program subroutine is used several 
times, the LIST=NO option provides ease and efficiency 
in coding. The subroutine linkage generated by LIST=NO 
has the coding format shown in Figure A-1. 


‘Figure A-1, Subroutine Linkage Coding Format 
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Example 


FISAVE (1B cece scary goa irc aes an 

NMG Rpt a ang yeh 
LISTENO,IDEMT=FILEG ow. 
WOENTHEILEG,LISTHYES 0. 
$00 rs eco omen ca a. 


Su broutine 
Linkage 
PUT 


Parameter 
List 


With the LODD instruction, the user loads the address of 
a parameter packet which has been specified elsewhere in 
the program (TAG4) and the address of the save area 
specified at SAVEIT. 


With the PUT macro and a LIST=NO parameter specified, 
a subroutine linkage is generated (IDENT must be 


specified). 


At address TAG4, the PUT parameter list is generated. 


LODO 


MUM 


LIST DEFAULT 


If the LIST option is omitted, subroutine linkage.coding is 
generated followed by the appropriate parameter list. The 
user must load R7 with the save area address. Figure A-2 
shows the subroutine linkage coding format for the 
default of the LIST option. 


Example 


ee rn ee ee Oe ee See Ce 


on oS A te ell 


ae oo Coe ae See nee ne SE 


Baer Cera fae an Ca em Cpe ROE Wee a Toe a Y 


Subroutine 
Linkage 
(Default) 


GET 
Parameter 
List 


The LIST default for the GET request results in the 
generation of the subroutine linkage and the GET param- 
eter list. 


Return Address 


a oes 27 r 


BDT Address (GET/PUT Macros) or DMOCC (OPENL/CLOSEL Macros) 


Figure A-2. LIST Default Subroutine Linkage Coding Format 


Table A-1. GET/PUT Parameter List Suftix* 


0 - Length of List LL 


2 2 i ca YM RA fsfal ms | fe 
6 | | a oan : 
« WLLL ; 
» WA... 


22 5 Record Address RA 


Description 


Length of parameter list. Always set to 4, 6, 8, 9, or 11. 


Function Codes (FC) 


Q GET 

1 PUT 

2 PUTU 

3. LOCRC 
7 DELR 
8 SETL 


Index external (I) \ 


0 Not indexed function 
1 Indexed function 


Record address (RA) 


0 No record address 
1° Record address 


Size parameter specified (S) 


0 No address specified in word 7 
1 Address of variable record size specified in word 7 


Return parameter specified (R) 


QO No address specified in word 9 
1 Return address specified for EOF or invalid key in word 9 


SETL flag (SL) 
00 Positions to BOF 
01 Positions to record equal to KEYADR2 


10 Positions to record greater than or equal to KEYADR2 


Error code, word contains the error code returned by the GET/PUT module if an 
error condition is detected. 


Segment tag for BDT 


BDT address (must be present) 


*The 2-character suffix for unique file identifier. 
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Table A-1. (Continued) 


Description 


Segment tag for record size address 


Record size address, If S=1 (byte 3, bit 4), this address must be present. This address 
points to a 2-byte location which contains the size (in binary) of the record, This 
parameter is required for PUT and PUTU and optional for GET. !t is ignored for 
fixed length records. 

Segment tag for end return address 


End return address, If R=1 (byte 3, bit 5), this parameter must be present. This address 
is where control is returned if EOF, EOA, or an invalid key occurs, 


Index external, If l=1 (byte 3, bit 2), this is the external address of the functional 
module of indexed GET/PUT macros. 


Segment tag for record address 


Record address, an optional record area that can be specified in each GET or PUT 


Table A-2, OPENL/CLOSEL Parameter List 


‘T S/S / CC 
5s WWMMMMH@q@e@_ 
LLL LMM STAG LAB 


Length of parameter list, always set to 6 
Function code (FC) 
4 OPENL (Uses CC, U, R, and LB) 
5 CLOSEL (Uses LK and R) 
6  CLOVEL (Uses none of these) 


Control character (CC) 


(8) ANSI control characters 
1 Device control characters 


Lock (IK) 
0 No lock 
1 Lock 
Usage (U) 
00 Input 
O1 tnput/output 
10 Output 
Rewind (R) 


0 No rewind 
1 Rewind 


Label (LB) 


QO  ~=No label address specified in word 7 
1 Label address specified in word 7 


Error code, word contains error code returned by the DMOCC module if an 
error condition is detected. 


Segment tag for BDT ~ 
BDT acidress (must be present) 
Segmenit tag for label address 


Label address. If LB=1 (byte 3, bit 7), this is the address of the label packet. 


*The 2-character suffix for unique file identifier. 


B. LINKAGE CONVENTIONS 


Program linkage is the process of linking separately 
generated object modules into an execution unit. The 
following two basic functions must be performed in 
a linkage process: 


Matching of external address references 


Actual transfer of control during execution 


The first function is performed by a linkage editor, 
and it is not discussed in this manual. The second 
function is the linkage conventions established for the 
MRX/OS. 


The basic linkage conventions for a calling program 
include: 


1. Using the proper registers to establish linkage 


2. Reserving an area that is used by the called 
program to refer to the parameter list. 


3. Reserving an area in which the contents of 
the registers may be saved. 


REGISTER USE 


The linkage requires one or two registers, depending 
upon the passing of the address of the parameter list 
to the called program. 


The user must load the save area address into gen- 
eral-purpose register 7 (R7). 


If the parameter list is elsewhere in the program, the user 
loads the address of the parameter list into 
general-purpose register 6 (R6). 


PARAMETER LIST 


The parameter list is a list of contiguous words starting on 
a word boundary. It is the expansion of the macro call. 
When the parameter list is not found immediately after 
the macro call, the location of this parameter list must be 
loaded into R6. 


SAVE AREA 


The calling program must reserve an area of 22 bytes 
(beginning on an even-byte boundary) to be used by 
the called program for saving registers. The calling 
programs must load the address of the save area into 
R7. 


: The following diagram illustrates the layout of the 


' gave area. 
| Save-area Return Address | 
+2 Previous Save Area Address 
+4 Status 
+6 Contents of Register 0 
+20 


Contents of Register 7 
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THE CALLING SEQUENCE 


The calling sequence has two forms, depending upon 
whether the return is in-line or out-of-line. 


In-Line 


NAME | OPERATION 
12 3 4 5 6 7 819] 10 11 1213 14 18 16 17 
. 


OPERAND 


19 20, 21, 22 23,24 25,26 27,28 29, 30, 31, 32,93, 34, 36, 36,37, 303940 41, 42 49.44 45,48 
PARALIST.,R... OPTIONAL. . 
ABAYI MG, BD cs 

ASU BR, ORD 


The parameter list address if elsewhere in the program, is 
loaded into R6. The address of the save area is loaded into 
R7. A branch and store register instruction saves the 
address of the next instruction in the return address of the 
save area. 
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Out-of-Line 


OPERATION | OPERAND 
10 11 12 13 14 16, 16 17] 18} 19 20 21 22 23 24 25 26 27.26 29 30 31 32.33 34 95 3837 3839 40 41 42 4344 45 46 
mr) ao tot 


The parameter list address, if elsewhere in the program, is 
loaded into R6. The address of the save area is loaded into 
R7. The address of the user return (MYRTN) is loaded 
into the return address of the save area. Then a branch to 
the subroutine is performed. 


C. PROGRAM FLOW 


The following figure illustrates the placement of the 
different macros in the program. 


The ID keyword of the Control Language //DEFINE 
statement and the IDENT keyword of OPENL/CLOSEL 
and GET/PUT correspond to the identifier entry of the 
define file macro. 


//DEF ID=FILE1,... 
//DEF ID=FILE2,... 
FILE1 DEFIF... 
FILE2 DEFSF... 


OPENL IDENT=FILE1,... 
OPENL IDENT=FILE2,... 


GET IDENT=FILE2, ... 


4 Subroutine 
PUT IDENT=FILE1,... 


CLOSEL !DENT=FILE1,... 
CLOSEL IDENT=FILE2,... 


HALT 
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_D. INDEX PORTION OF INDEXED FILE 


The following diagram (Figure D-1) gives the relationship 
of the different parts of the index portion of an indexed 
file. 


Block 1 information Block 
Primary Index Blocks 
Available Space 
Block n Directory to the Directory Block 
n+1 7 


Directory Index Blocks 


Figure D-1, Index Portion of an indexed File Layout 


The layouts of the individual blocks are found in the 
succeeding sections of this appendix. 


INFORMATION BLOCK 


The Information Block of the Index portion of an 
indexed file gives the addresses of the last blocks of the 
data portion and index portion of the indexed file that 
were written. This enables Data Management to make 
further additions to the file. Figure D-2 gives the fields of 
the Information Block. 


Common Stored Data Record Header 


Pass Boundary Index Track Boundary Index 


Block Address of Last Spattered Block Written 


Available Space Block Address 


Block Address of Directory to the Directory 


Block Address of the Last Directory Index Block 


Common Stored Data Space Header 
(1-3 bytes length) 


Figure D-2. Information Block 


DIRECTORY TO THE DIRECTORY BLOCK 


Figure D-3 gives the layout of the Directory to the 
Directory block. Each key value has an associated 
directory index block address. 


Byte 0O Record Header 
2 
4 - Previous Block Link* 
6 Next Block Link* 
8 Count of Values in Block 
10 Key Value 1 
(1-100 Character EBCDIC) Key 1 
m Pointer to Directory Index Block 
m+2 
pon Key Value 2 Key 2 
n Pointer to Directory Index Block 
n+2 


Space Header 
and 
Available Space 


Figure D-3. Directory to the Directory Block 


DIRECTORY INDEX BLOCK 


Figure D-4 gives the layout of the Directory Index block. 
Each key value has an associated primary index block 


address. 
Byte 0 Record Header 
2 
4 Previous Block Link* 
6 Next Block Link* 
8 Count of Values in Block 
10 
Key Value 1 
(1-100 Character EBCDIC) Key 1 
ao Pointer to Primary Index Block 
m+2 Key Value 2 
key 2 
n Pointer to Primary Index Block 
nt+2 : 


Space Header 
and 
Available Space 


Figure D-4, Directory Index Block 


*The previous block link and next block link entries are not used in the directory blocks; they are reserved for 


future use. 
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PRIMARY INDEX BLOCK 


Figure D-5 gives the layout of the Primary Index block. 
Edch key value has an associated block record address. 


Byte 


Record Header 


aan eeeeenaens aeneeeaninenenemenemenenn mnael 


Previous Black Link 


Next Block Link 


Count of Values in Block 


Key Value 1 


(1-100 Character EBCDIC Key 1 
Logical Block Number 
Record Number 
Key Value 2 
Key 2 


Logical Block Number 


| Record Number 


Space Header 
and 
Available Space 


Figure 0-5. Primary Index Block 
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Access 
Block 


Block I/O level 


Buffer switching 


Catalog 
Close 
Control Language 


statement 


Directive 
Debug 


Dump 
File 


File identifier 
File name 


Global register 
save area 


Information 
retrieval 


Job 


Job step 


GLOSSARY 


Process of obtaining information from or placing information into storage. 


A set of words, characters, or records that are recorded as a unit. 


A processing level recognizing no logical records. Data is read or written as a physical 
data block. Further processing of logical records is a user responsibility. 


The transfer of processing from one buffer to another when two buffers are specified. 


Ordered compilation of item descriptions and sufficient information to give access to 
those items. 


A function that makes a file unavailable for further processing and does label 
processing for end of file. 


A statement in a job that is used in identifying the job or describing its requirements to 
the operating system. 


A control statement (as opposed to data) supplied to a program for the purpose of 
directing its mode of operation. 


The detection, location, and removal of mistakes from a routine or malfunctions from 
a computer. 


Copying of contents from internal storage to an external storage. 

A collection of related records treated as a unit. 

Identification given by the DEFSF, DEFRF, or DEFIF macro and referenced as the 
IDENT parameter of the GET/PUT and OPEN/CLOSE macros. IDENT is synonymous 
with the IDENTIFIER (ID) keyword of the Control Language //DEFINE statement. 
Cataloged name of file given by the FILENAME (FIL) keyword of the Control 
Language //DEFINE statement. This corresponds to the FILENAM parameter of the 
DEFLB macro. 


Storage area used for saving and restoring user registers that can be used by several 
routines. 


Method and procedure of recovering specific information from stored data. 


A specified group of logically related tasks prescribed as a unit of work for a computer. 


The execution of a computer program explicitly identified by a Control Language 
statement. A job may specify that several job steps be executed. 


Glossary-1 
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Key 
Label 


Load point 


Logical 1/O level 


Macro, action 


Macro, data 


Macro, system 


Modification 
security code 


Open 


Packing 


Physical 1/O level 


Record 

Record identifier 
Relative record 
number 

Split cylinder 
Tag 


Tape mark (TM) 


Thread 


Unblocked record 


Characters within a data item that are used to identify it or control its use. 
Symbols identifying or describing an item, record, message, or file. 


Preset point (reflector strip) at which magnetic tape is initially positioned under the 
read/write head to start processing. 


A processing level that reads and writes logical records. Data Management does the 
blocking and deblocking. 


Macro which generates executable code that results in some action being taken at 
execution time. Such a macro is always coded in line with the executable part of the 
program. 

Macro which generates nonexecutable code, such as an |/O control table, and should 
usually be coded in a data area of the program where an attempt to execute it (by 
mistake) is unlikely. Some macros are inherently data macros in any form while any 
system macro may become a data macro by including the parameter LIST=YES. 
Instructions through which the user avails himself of the various system services, such 
as 1/O processing. They form an extension to the standard machine instruction set and 


result in the generation of code which provides an interface with the system. 


Code that restricts access to a file for security purposes. 
Function making file available for processing by checking label and file attributes. 


Contiguous placement of records with no space in between records in a buffer. 


The lowest level of I/O implementation available to the user. The user may have more 
responsibility for details, but gains in flexibility. This level of coding is independent of 
the system file organizations. 


Group of related items of data that are treated as a unit. 


Identification of a record in terms of block number and relative position within that 
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